nevalang · emil14 · Dec 15, 2024 · Dec 15, 2024 · Dec 16, 2024 · Dec 16, 2024
diff --git a/.cursorrules b/.cursorrules
@@ -1,2 +1,3 @@
+- never remove my comments
 - write comments in lowercase
 - write names for table-driven test-cases in lower_snake_case
diff --git a/.vscode/bookmarks.json b/.vscode/bookmarks.json
@@ -0,0 +1,14 @@
+{
+	"files": [
+		{
+			"path": "internal/compiler/analyzer/nodes.go",
+			"bookmarks": [
+				{
+					"line": 213,
+					"column": 2,
+					"label": ""
+				}
+			]
+		}
+	]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -7,8 +7,8 @@
       "request": "launch",
       "mode": "auto",
       "program": "${workspaceFolder}/cmd/neva",
-      "cwd": "${workspaceFolder}/e2e/filter_list",
-      "args": ["run", "--trace", "main"]
+      "cwd": "${workspaceFolder}/examples",
+      "args": ["run", "--trace", "unions_tag_only"]
     },
     {
       "name": "DEBUG CODEGEN",

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,7 +10,6 @@ Start from reading [ARCHITECTURE.md](./ARCHITECTURE.md) and [Makefile](./Makefil
 - Make: https://www.gnu.org/software/make/#download
 - NodeJS and NPM: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/
 - Antlr: `pip install antlr4-tools`
-<!-- - Tygo: `go install github.com/gzuidhof/tygo@latest` -->
 
 ### VSCode
 
@@ -29,12 +28,6 @@ Not required but recommended:
 2. If something doesn't work, run `/parser/smoke_test`
 3. To debug deeper, make sure `neva.g4` is opened in the editor and launch VSCode's `ANTLR` debug task
 
-<!-- ## VSCode Extension
-
-VSCode extension depends on types defined in the `sourcecode` and `typesystem` packages so it's dangerous to rename those. If you going to do so, make sure you did't brake TS types generation.
-
-Check out [tygo.yaml](./tygo.yaml). and `CONTRIBUTING.md` in "vscode-neva" repo. -->
-
 ## Learning Resources
 
 ### Dataflow
@@ -168,10 +161,6 @@ Two reasons:
 
 Actually it's impossible to have desugarer before analysis. It's possible to have two desugarers - one before and one after. But that would make compiler much more complicated without visible benefits.
 
-### Why union types are allowed for constants at syntax level?
-
-You indeed can declare `const foo int | string = 42` and that won't make much sense. The problem it's not enough to restrict that at root level, you also have to recursively check every complex type like `struct`, `list` or `map`. And that is impossible to make at syntax level and require work in analyzer. This is could be done in the future when we cover more important cases.
-
 ### Why we have special syntax for union?
 
 We don't have sugar for `maybe<T>` and `list<T>` so why would we have this for unions? The reason is union is special for the type system. It's handled differently at the level of compatibility checking and resolving.

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/comparison.md b/docs/comparison.md
@@ -0,0 +1,48 @@
+# Comparison (Nevalang vs X)
+
+## Neva vs Go
+
+Neva is built on top of Go and it tries to borrow as much good things from there as possible, no surprise they have a lot in common: both statically typed, compiles to machine code, have garbage collector, builtin concurrency, both tries to be small and simple, and both aim for great developer experience with dependency management and other tooling.
+
+The difference is that Go's paradigm is mixed - control-flow plus dataflow subset. Nevalang on the other hand is purely dataflow. It means that Go mostly operates in abstractions such as call/return, callstack, expression evaluation. It's actually expects you to control execution flow at the level of imperative instructions like `break`, `continue` and even `goto`. The dataflow subset is what's known as [CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes) implemented as goroutines and channels. CSP is indeed dataflow but it's usage is limited in Go and programs are mostly control-flow. Go also allows control-flow concurrency with mutexes and shared state. Concurrent Go code is usually considered as harder to reason about and more error prone, despite Go having state of the art concurrency support among all popular languages.
+
+| **Feature**              | **Neva**                                                            | **Go**                                                                            |
+| ------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Paradigm**             | Pure Dataflow - nodes send and receive messages through connections | Mixed - control-flow (imperative) + dataflow subset (CSP)                         |
+| **Concurrency**          | Defaults to concurrency. Requires explicit synchronicity            | Defaults to synchronicity. Requires explicit concurrency.                         |
+| **Error Handling**       | Errors as values with `?` operator to avoid boilerplate             | Errors as values with `if err != nil {}` boilerplate                              |
+| **Mutability**           | Immutable - no variables and pointers; data races are not possible  | Mutable - variables and pointers; programmer must avoid data races                |
+| **Null Safety**          | Yes - nil pointer dereference is impossible                         | No - nil pointer dereference is possible                                          |
+| **Zero Values**          | No zero values - everything must be explicitly initialized          | Zero values by default - everything can be initialized implicitly                 |
+| **Subtyping**            | Structural - types are equal by their shape                         | Nominal - types are equal by their name                                           |
+| **Traceback**            | Automatic - every message traces its path                           | Manual - programmer must explicitly wrap every error to add context               |
+| **Dependency Injection** | Built-in - any component with dependency expects injection          | Manual - programmer must create constructor function that takes dependencies      |
+| **Stream Processing**    | Native support with components like `Map/Filter/Reduce`             | Programmer must manually implement dataflow patterns with goroutines and channels |
+| **Visual Programming**   | Aims for hybrid programming with Visual Editor (WIP)                | Textual language, very little visual tooling support                              |
+
+## Neva vs Erlang/Elixir
+
+People often compare Neva to BEAM langauges because of message-passing, immutability, concurrency and stream-processing:
+
+| **Feature**            | **Neva**                                                            | **Erlang/Elixir**                                             |
+| ---------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Paradigm**           | Pure Dataflow - no functions, no call-stack; Just message-passing   | Mixed - control-flow (FP) with dataflow subset (actors)       |
+| **Message Passing**    | Static connections defined at compile time                          | Dynamic message passing to PIDs                               |
+| **Type-System**        | Strongly Typed - types are always required                          | Dynamic (Erlang) / Gradually-typed (Elixir)                   |
+| **Execution Model**    | Compiles to machine code and can be deployed as a single executable | Needs Virtual-Machine (BEAM) to be installed on the server    |
+| **Syntax**             | C-like syntax with curly-braces                                     | Esoteric (Erlang) / Ruby-like (Elixir)                        |
+| **Error Tolerance**    | Everything must be type-safe; Errors must be explicitly handled     | "Let it crash"                                                |
+| **Visual Programming** | Aims for hybrid programming with Visual Editor (WIP)                | Textual language, very little visual tooling support          |
+| **Interop**            | Aims for interopability with Golang (WIP)                           | Interopable with BEAM-compatible family (Erlang/Elixir/Gleam) |
+
+## Neva vs Gleam
+
+BEAM family includes language that is even closer to Neva because of static types. However, there are differences:
+
+| **Feature**            | **Neva**                                                            | **Gleam**                                                     |
+| ---------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Paradigm**           | Pure Dataflow - no functions, no call-stack; Just message-passing   | Mixed - control-flow (FP) with dataflow subset (actors)       |
+| **Subtyping**          | Structural - types are equal by their shape                         | Nominal - types are equal by their name                       |
+| **Execution Model**    | Compiles to machine code and can be deployed as a single executable | Needs Virtual-Machine (BEAM) to be installed on the server    |
+| **Interop**            | Aims for interopability with Golang (WIP)                           | Interopable with BEAM-compatible family (Erlang/Elixir/Gleam) |
+| **Visual Programming** | Aims for hybrid programming with Visual Editor (WIP)                | Textual language, very little visual tooling support          |
diff --git a/docs/terminology.md b/docs/terminology.md
@@ -0,0 +1,30 @@
+# Terminology
+
+This document explains key terms used throughout the documentation and how they are applied.
+
+## Paradigm
+
+A programming paradigm is a set of abstractions that describe computation and form a hierarchical tree of different approaches.
+
+```mermaid
+---
+title: Simplified Overview
+---
+graph TD
+    paradigm --> control-flow
+    paradigm --> dataflow
+    control-flow --> structural
+    control-flow --> object-oriented
+    control-flow --> functional
+    dataflow --> flow-based
+    dataflow --> csp
+    dataflow --> actor-model
+```
+
+## Control-Flow
+
+Control-flow is a top-level paradigm that describes computation as a series of steps that are executed sequentially.
+
+## Dataflow
+
+Dataflow is a top-level paradigm that describes computation as a network of nodes that perform message-passing.
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -1,6 +1,6 @@
 # Tutorial
 
-Welcome to a tour of the Nevalang programming language. This tutorial will introduce you to Nevalang through a series of guided examples.
+Welcome to a tour of the Neva programming language. This tutorial will introduce you to Nevalang through a series of guided examples.
 
 1. [Welcome](#welcome)
    - [What kind of language is this?](#what-kind-of-language-is-this)
@@ -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.
@@ -944,6 +944,8 @@ You should never do that if it's possible to follow "switch-true" pattern, becau
 
 #### Multiple Sources
 
+> WARNING: This is important section. **Don't skip** it!
+
 One might ask, why didn't we cover multiple case senders if we covered multiple receivers? When using switch with multiple case receivers, it works differently than in control flow languages. For example:
 
 ```neva
@@ -956,3 +958,42 @@ switch {
 Is **not** "if either Alice or Bob then do uppercase". It's a fan-in, meaning `Alice` and `Bob` are concurrent. Switch will select the first value sent as a case, which is random since both are message literals.
 
 > These semantics might change in the future. There's an [issue](https://github.com/nevalang/neva/issues/788) about that.
+
+**How To Cover this Case?**
+
+```neva
+pass1 Pass{Upper}
+pass2 Pass{Upper}
+---
+... -> switch {
+    'Alice' -> pass1
+    'Bob' -> pass2
+    _ -> lower
+}
+[pass1, pass2] -> upper
+```
+
+With a little bit of boilerplate 
+
+**WARNING** (Possible Concurrency Issues)
+
+`[pass1, pass2] -> upper` guarantees that `upper` receives messages in the exact same order as they are sent by `pass1` and `pass2` nodes. And `switch` guarantees that it will never reiceve next message from it's sender  `... ->` until previously selected receiver has received.
+
+BUT switch doesn't know about `[pass1, pass2] -> upper`. It will wait for `pass1` and `pass2` to receive yes, but it will not wait `pass1` and `pass2` to _send_!
+
+Example: let's say we send `'bob', 'alice'` sequence to our switch. This sequence of events is totally possible:
+
+```
+pass1 received alice and blocked
+pass2 received bob and blocked
+pass2 send BOB and unlocked
+pass1 send ALICE and unlocked
+```
+
+For `[pass1, pass2] -> upper` connection it will mean that `upper` must receive `BOB` _before_ `Alice` which is not correct!
+
+*Safe Solution*
+
+This situation will never happen if you guarantee that your component never receive next input until it previous sent result is received. But this can only be guaranteed by the parent of your compnent.
+
+Idiomatic way would be to use higher-order component, that can wrap your concurrent component and use it in a safe way, so it will process messages fully sequentionally - synchronized.
diff --git a/e2e/99_bottles_verbose/main/main.neva b/e2e/99_bottles_verbose/main/main.neva
@@ -1,4 +1,7 @@
-import { fmt }
+import {
+    fmt
+    runtime
+}
 
 // https://www.99-bottles-of-beer.net
 
@@ -40,7 +43,7 @@ def PrintFirstLine(n int) (n int) {
     p2 fmt.Println
     printf fmt.Printf
     lock Lock<int>
-    panic Panic
+    panic runtime.Panic
     ---
     :n -> [s:data, lock:data]
 
@@ -73,7 +76,7 @@ def PrintSecondLine(n int) (n int) {
     p3 fmt.Println
     printf fmt.Printf
     lock Lock<int>
-    panic Panic
+    panic runtime.Panic
     ---
     :n -> [s:data, lock:data]
 

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/main/main.neva b/e2e/add_nums_from_stdin_naive/main/main.neva
@@ -1,4 +1,8 @@
-import { strconv, fmt }
+import {
+    fmt
+    runtime
+    strconv
+}
 
 def Main(start any) (stop any) {
 	scanner1 fmt.Scanln
@@ -7,7 +11,7 @@ def Main(start any) (stop any) {
 	parser2 strconv.ParseNum<int>
 	add Add<int>
 	println fmt.Println<int>
-	panic Panic
+	panic runtime.Panic
 	---
 	:start -> scanner1:sig
 	scanner1:res -> parser1:data

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/main/main.neva b/e2e/add_nums_from_stdin_with_default_any/main/main.neva
@@ -1,9 +1,13 @@
-import { strconv, fmt }
+import {
+    fmt
+    runtime
+    strconv
+}
 
 def Main(start any) (stop any) {
 	aux Aux
 	println fmt.Println
-	panic Panic
+	panic runtime.Panic
 	---
 	:start -> aux:sig
 	aux:res -> println:data

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