Merge pull request #870 from nevalang/readme-update

`errors` package
nevalang · Feb 9, 2025 · 4d833b1 · 4d833b1
2 parents 41c3b01 + c56cd3f
commit 4d833b1
Show file tree

Hide file tree

Showing 108 changed files with 320 additions and 138 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -7,7 +7,7 @@
       "request": "launch",
       "mode": "auto",
       "program": "${workspaceFolder}/cmd/neva",
-      "cwd": "${workspaceFolder}/e2e/filter_list",
+      "cwd": "${workspaceFolder}/e2e/for_with_range_and_if",
       "args": ["run", "--trace", "main"]
     },
     {

diff --git a/README.md b/README.md
@@ -15,32 +15,37 @@
 | [**Contributing**](./CONTRIBUTING.md)
 | [**Architecture**](./ARCHITECTURE.md)
 
-![tests](https://github.com/nevalang/neva/actions/workflows/test.yml/badge.svg?branch=main) ![lint](https://github.com/nevalang/neva/actions/workflows/lint.yml/badge.svg?branch=main) [![go report](https://goreportcard.com/badge/github.com/nevalang/neva)](https://goreportcard.com/report/github.com/nevalang/neva) [![Discord](https://img.shields.io/discord/1094102475927203921?logo=discord&logoColor=white&color=5865F2)](https://discord.gg/dmXbC79UuH) [![ChatGPT](https://img.shields.io/badge/Nevalang_AI-74aa9c?logo=openai&logoColor=white)](https://chatgpt.com/g/g-RhZn00MXU-nevalang-expert) ![OS](https://img.shields.io/badge/os-windows%20%7C%20macos%20%7C%20linux-lightgrey?logo=linux&logoColor=white) ![Go](https://img.shields.io/badge/v1.23-00ADD8?logo=go&logoColor=white) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Tests CI](https://github.com/nevalang/neva/actions/workflows/test.yml/badge.svg?branch=main)
+![Linting CI](https://github.com/nevalang/neva/actions/workflows/lint.yml/badge.svg?branch=main)
+[![Go Report](https://goreportcard.com/badge/github.com/nevalang/neva)](https://goreportcard.com/report/github.com/nevalang/neva)
+![GitHub closed issues](https://img.shields.io/github/issues-closed/nevalang/neva)
+[![Discord](https://img.shields.io/discord/1094102475927203921?logo=discord&logoColor=white&color=5865F2)](https://discord.gg/dmXbC79UuH)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![OS](https://img.shields.io/badge/os-linux%20%7C%20mac%20%7C%20windows-lightgrey?logo=linux&logoColor=white)
+[![ChatGPT](https://img.shields.io/badge/Neva_GPT-74aa9c?logo=openai&logoColor=white)](https://chatgpt.com/g/g-RhZn00MXU-nevalang-expert)
 
 <p align="center">
   <img src="./assets/animations/dataflow.gif" alt="Dataflow">
 </p>
 </div>
 
-## 🤔 What Is Nevalang?
-
-> **⚠️ WARNING**: This project is under active development and not yet production-ready!
+> ⚠️ WARNING: This project is under active development and not yet production-ready!
 
-Neva is a new kind of programming language where instead of writing step-by-step instructions you create **networks** where data flows between **nodes** as immutable messages and everything runs in **parallel** by default. After type-checking, your program is compiled into **machine code** and can be distributed as a **single executable** with zero dependencies.
+## 🤔 What Is Nevalang?
 
-Combined with built-in **stream processing** support and features like **advanced error handling**, Nevalang is the perfect choice for **cloud-native applications** requiring **high concurrency**.
+Nevalang is a new kind of programming language where instead of writing step-by-step instructions, you create networks where data flows between nodes as immutable messages, with everything running in parallel by default. After type-checking, your program is compiled into machine code and can be distributed as a single executable with zero dependencies.
 
-Future updates will include **visual programming** and **Go interoperability** to allow gradual adoption and leverage existing ecosystem.
+Neva excels at stream processing and concurrency while remaining simple and enjoyable for general development. Future updates will add visual programming and Go interop to enable gradual adoption.
 
 ### Why Yet Another Programming Language?
 
-We created Nevalang because we saw a gap in the programming language landscape:
+We created it because we saw a gap in the programming language landscape:
 
-1. **Visual Programming Done Right** - While there are many visual programming tools, they're usually limited to specific domains or lack the power of traditional programming. Nevalang is designed from the ground up to be a hybrid visual/text-based programming environment.
-2. **Simple Parallel Programming** - Most languages treat concurrency as an advanced feature, making it complex and error-prone. In Nevalang, parallelism is the default, and the language design prevents common issues like data races.
-3. **Modern Developer Experience** - We combine the best ideas from modern languages with dataflow programming to create a unique development experience focused on productivity.
+1. **Visual Programming Done Right** - existing visual tools are limited to specific domains or lack the power of traditional programming languages. Neva is designed from the ground up to be a hybrid visual/textual programming language.
+2. **Simple Parallelism** - Most languages treat concurrency as an advanced feature. In Neva, parallelism is the default and it prevents issues like data races.
+3. **Modern Developer Experience** - We combine best ideas from modern languages with dataflow paradigm to make programming easy and fun.
 
-Finally, we believe exploring new programming paradigms is valuable for the entire programming community, even if only to learn what works and what doesn't.
+Finally, exploring new programming paradigms helps advance the field by discovering what works and what doesn't!
 
 ## 👋 Hello, World!
 
@@ -49,16 +54,25 @@ import { fmt }
 
 def Main(start any) (stop any) {
 	println fmt.Println<string>
+	panic Panic
 	---
-	:start -> 'Hello, World!' -> println -> :stop
+	:start -> 'Hello, World!' -> println
+	println:err -> panic
+	println:res -> :stop
 }
 ```
 
 What's happening here:
 
-- `import { fmt }` loads the `fmt` package for printing
-- `def Main` defines the main component with input port `start` and output port `stop` of type `any` (it's safe since it's only used as a signal)
-- `:start -> 'Hello, World!' -> println -> :stop` defines a connection that sends the string to `println` when program starts and terminates after printing (runtime sends a message to `Main:start` at startup and waits for `Main:stop` to terminate)
+- `import { fmt }` loads fmt package for printing
+- `def Main(start any) (stop any) {...}` defines component with input port start and output port stop, both of type any (it's safe since they used as signals)
+- `println fmt.Println<string>` defines a node, instance of fmt.Println
+- `panic Panic` defines another node to crash the program
+- `:start -> 'Hello, World!' -> println` defines a connection that sends the string to println when the program starts
+- `println:err -> panic` handles the possible error by crashing the program
+- `println:res -> :stop` terminates the program after successful printing
+
+> Runtime sends a message to `Main:start` at startup and waits for `Main:stop` to terminate
 
 ## 🔥 Features
 
@@ -77,9 +91,9 @@ What's happening here:
 - **Go Interoperability** (WIP): Call Go from Neva and Neva from Go
 - **NextGen Debugging** (WIP): Observe execution in realtime and intercept messages on the fly
 
-## 🧐 Why Use Nevalang?
+## 🧐 Why Use Neva?
 
-Let's compare Nevalang with Go. We could compare it to any language but Go is a simple reference since Nevalang is written in Go.
+Let's compare Neva with Go. We could compare it to any language but Go is a simple reference since Neva is written in Go.
 
 | **Feature**              | **Neva**                                                           | **Go**                                                                            |
 | ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |

diff --git a/benchmarks/neva.yml b/benchmarks/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/docs/book/program_structure.md b/docs/book/program_structure.md
@@ -36,10 +36,10 @@ Module is usually a git-repo but not necessary. Module that isn't published in g
 
 ### Manifest File
 
-The manifest defines the module's minimum supported language version and dependencies. Here's an example manifest with a dependency on the Nevalang compiler version `0.30.2` and a third-party module:
+The manifest defines the module's minimum supported language version and dependencies. Here's an example manifest with a dependency on the Nevalang compiler version `0.31.0` and a third-party module:
 
 ```yaml
-neva: 0.30.2
+neva: 0.31.0
 deps:
   github.com/nevalang/x:
     path: github.com/nevalang/x
@@ -51,7 +51,7 @@ The `deps` field is a map where each dependency has an alias. When adding depend
 > WIP: CLI tool planned for CI/CD to verify module's backward compatibility
 
 ```yaml
-neva: 0.30.2
+neva: 0.31.0
 deps:
   github.com/nevalang/x@0-0-12:
     path: github.com/nevalang/x

diff --git a/docs/style_guide.md b/docs/style_guide.md
@@ -28,22 +28,26 @@ Group imports by type: stdlib, third-party, local. Separate groups with newlines
 
 Names should inherit context from parent scope. Good naming eliminates need for comments. Names generally rather short than long.
 
-- **Packages/Files**: `lower_snake_case` up to 3 words
-- **Types**: `CamelCase` up to 3 words
-- **Interfaces**: `CamelCase` with `I` prefix up to 3 words
-- **Constants**: `lower_snake_case` up to 3 words
-- **Components**: `CamelCase` noun up to 3 words
-- **Nodes**: `lowerCamelCase` up to 3 words
-- **Ports**: `lowercase`, up to 5 characters
+- **Packages/Files**: `lower_snake_case`
+- **Types**: `CamelCase`
+- **Interfaces**: `CamelCase` with `I` prefix
+- **Constants**: `lower_snake_case`
+- **Components**: `CamelCase` noun
+- **Nodes**: `lower_snake_case`
+- **Ports**: `lowercase`
 
 ## Interfaces
 
 - Use outports to separate data flows, not for destructuring.
-- Use `data` for input with payload, `sig` for input without payload (trigger), `res` for output with payload, `sig` for output without payload (success), and `err` for failures.
-- `err` outport must be of type `error`. `sig` inport must be of type `any` for flexibility. Never use `any` for `res` outport.
-- Don't send input data downstream; the parent already has it.
-- Use type-parameters to preserve type info between input and output.
+- Use `data` for input, `res` for output and `err` for failures.
+- Outport `err` must be of type `error`.
+- Ports `data` and `res` of type `any` are interpreted as signals.
+- Use name `sig` if you have _extra_ trigger-inport.
+- Use names `then` and `else` if you implement boolean branching.
+- Use specific inport names if have more than one - e.g. `(filename, data)` for `io.WriteAll`.
+- Use type-parameters to preserve type info between input and output if needed.
 
 ## Networks
 
 - Omit port names when possible. It enables renaming of ports without updating the networks.
+- Use `?` for to propogate errors except custom error handling is needed.
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -77,7 +77,7 @@ After installation is finished, you should be able to run the `neva` CLI from yo
 neva version
 ```
 
-It should emit something like `0.30.2`
+It should emit something like `0.31.0`
 
 ### Hello, World!
 
@@ -256,7 +256,7 @@ This structure introduces two fundamental concepts in Nevalang: modules and pack
 A module is a set of packages with a manifest file (`neva.yaml`). When we created our project with `neva new`, it generated a basic module with the following manifest file:
 
 ```yaml
-neva: 0.30.2
+neva: 0.31.0
 ```
 
 This defines the Nevalang version for our project. As your project grows, you can include dependencies on third-party modules here.

diff --git a/e2e/99_bottles_verbose/neva.yml b/e2e/99_bottles_verbose/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_from_stdin_naive/neva.yml b/e2e/add_nums_from_stdin_naive/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_from_stdin_with_default_any/neva.yml b/e2e/add_nums_from_stdin_with_default_any/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_from_stdin_with_err_handling/neva.yml b/e2e/add_nums_from_stdin_with_err_handling/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_from_stdin_with_multuple_senders/neva.yml b/e2e/add_nums_from_stdin_with_multuple_senders/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_from_stdin_with_sub_components/neva.yml b/e2e/add_nums_from_stdin_with_sub_components/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/add_nums_verbose/neva.yml b/e2e/add_nums_verbose/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/array_inport_holes/neva.yml b/e2e/array_inport_holes/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/array_outport_holes/neva.yml b/e2e/array_outport_holes/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/binary_operators/arithmetic/add_floats/neva.yml b/e2e/binary_operators/arithmetic/add_floats/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/add_ints/neva.yml b/e2e/binary_operators/arithmetic/add_ints/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/add_strings/neva.yml b/e2e/binary_operators/arithmetic/add_strings/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/divide_floats/neva.yml b/e2e/binary_operators/arithmetic/divide_floats/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/divide_ints/neva.yml b/e2e/binary_operators/arithmetic/divide_ints/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/modulo/neva.yml b/e2e/binary_operators/arithmetic/modulo/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/multiply_floats/neva.yml b/e2e/binary_operators/arithmetic/multiply_floats/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/multiply_ints/neva.yml b/e2e/binary_operators/arithmetic/multiply_ints/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/power/neva.yml b/e2e/binary_operators/arithmetic/power/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/subtract_floats/neva.yml b/e2e/binary_operators/arithmetic/subtract_floats/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/arithmetic/subtract_ints/neva.yml b/e2e/binary_operators/arithmetic/subtract_ints/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/bitwise/and/neva.yml b/e2e/binary_operators/bitwise/and/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/bitwise/left_shift/neva.yml b/e2e/binary_operators/bitwise/left_shift/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/bitwise/or/neva.yml b/e2e/binary_operators/bitwise/or/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/bitwise/right_shift/neva.yml b/e2e/binary_operators/bitwise/right_shift/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/bitwise/xor/neva.yml b/e2e/binary_operators/bitwise/xor/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/equal/neva.yml b/e2e/binary_operators/comparison/equal/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/greater_int/neva.yml b/e2e/binary_operators/comparison/greater_int/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/greater_or_equal_int/neva.yml b/e2e/binary_operators/comparison/greater_or_equal_int/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/less_int/neva.yml b/e2e/binary_operators/comparison/less_int/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/less_or_equal_int/neva.yml b/e2e/binary_operators/comparison/less_or_equal_int/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/comparison/not_equal/neva.yml b/e2e/binary_operators/comparison/not_equal/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/logical/and/neva.yml b/e2e/binary_operators/logical/and/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/binary_operators/logical/or/neva.yml b/e2e/binary_operators/logical/or/neva.yml
@@ -1 +1 @@
-neva: 0.30.2 
+neva: 0.31.0 
diff --git a/e2e/classify_int/neva.yml b/e2e/classify_int/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/cli/build_windows/neva.yml b/e2e/cli/build_windows/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/cli/new_and_run/neva.yml b/e2e/cli/new_and_run/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/comments/neva.yml b/e2e/comments/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/compiler_error_unused_outport/neva.yml b/e2e/compiler_error_unused_outport/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/const_refs_verbose/neva.yml b/e2e/const_refs_verbose/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/div_test/neva.yml b/e2e/div_test/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/do_nothing_verbose/neva.yml b/e2e/do_nothing_verbose/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/duplicate_receiver/neva.yml b/e2e/duplicate_receiver/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0
diff --git a/e2e/duplicate_sender/neva.yml b/e2e/duplicate_sender/neva.yml
@@ -1 +1 @@
-neva: 0.30.2
+neva: 0.31.0