# *zwl* (zongors world language) Design parameters

## What is *zwl*?

*zwl* is an esoteric programming language that is trying way too hard to be a serious programming language.

It is inspired by both [esoteric programming languages](https://esolangs.org/wiki/Esoteric_programming_language), like [var'aq](https://web.archive.org/web/20091026213516/http://geocities.com/connorbd/varaq/), [uiua](https://www.uiua.org/), and [TIS-100 assembly](https://www.zachtronics.com/images/TIS-100P%20Reference%20Manual.pdf) and serious programming languages like C, Perl, Common Lisp, Lua, Rust, Go, Odin, Zig, Elixir, and Haskell.

## What are the features in *zwl*?

In general the paradigms are designed to be: var'aq-like, Interpreted, Distributed, Concurrent, and have an option to be JIT.

## What is the purpose of this language?

*zwl* acts as the assembly language for the universe machine. it allows for a user to manipulate the world machine. 

# *zwl* Grammar and Specification

How do I read these operations?

With most of the operations below they will be in the follwing format

anything between « » should be read as a type of thing and not a literal

for any operations they will look like

« input arguments » `operator` « output arguments »

unless stated you should assume that any arguments are pushed or poped from the nodes stack, if it does not return a value I will use `-`

## Form

- describe storage objects "the ideal state of the object"
- atoms (invoked forms) are stored in the internal database which is why they need version numbers
- Forms can be implementations of interfaces, collsions are not important as the names of interfaces only carry what needs to be implemented a not any implemtntation itself. for people coming from OOP you can think of this similar to an abstract class.
- there are also a list of "substantial forms" which come with the language which are the building blocks for more complex forms. If you are coming from object oriented languages you can think of this as "primitive types"

string for the command
this returns how many dimensions it can exist in, 0th means non drawable, 2 means 2D GUI usually, 3 means 3D object, and >3 is somthing you will have to implement yourself, e.g. miegakure
this is for the unit/measures system
some kind of procedure to draw the element in space or None
a position in space or None
a list containing the data of that form

"form name" «dimensions» «unit» «display» «position» «data» `frmdef` -

# Substantial Forms

## numeric

### bit (or unsigned units)

«hex number» 8  `u` u8

«hex number» «hex number» 16 `u` u16

«hex number» «hex number» «hex number» 32 `u` u32

«hex number» «hex number» «hex number» «hex number» 64 `u` u64

### integer (signed)

«hex number» 8  `i` u8

«hex number» «hex number» 16 `i` u16

«hex number» «hex number» «hex number» 32 `i` u32

«hex number» «hex number» «hex number» «hex number» 64 `i` u64

### real

«hex number» «hex number» «hex number» 32 `f` f32

«hex number» «hex number» «hex number» «hex number» 64 `f` f64

## string

" «utf8 encoded characters» `"` string

strings are always utf8, other formats will need to be done manually

## logical

- `true` bool

- `false` bool

### panic

calling panic on a variable that has an error will halt execution of the node that is running. it will broadcast the reason to the main kernel and to all other nodes listening

"reason" `panic` -

## datastructures

### list

A list will act similar to a list in LISP, it is esentially a block of memory that has an internal "length" and other operations.

syntax

(item1 item2 …)

### Basic operators

The following is a list of global operators and their effect:

comment (looks for another ! to close)
! any raw text here `!` -

anonymous subtroutine    
{ … `}` subroutine

sets a value in the node's map
`set`

delete from node's map
`del`

`add`

`sub`

`mul`
 
`div`
 
`pow`
 
`eq`
 
`ne`
 
`mod`
 
`not`
 
`and`
 
`or`

`nor`

`nand`

`xor`

`band`

`bor`

`bnor`

`bxor`

## Atom

An atom is an invoked form.
For those of you coming from an object oriented language
this is similar to creating an object on the heap using "new" keyword or the like

Atoms are pushed onto the stack of the node they are running in.

Here is an example of creating an atom and storing it as a variable in nram (the nodes map)

"atom name" («fields», …) `«form»` set

## Tunnel

Represents a path to a file, url endpoint, other process endpoint (like a socket, etc.)

Tunnels are inspired by translators in gnu/hurd, plan9 9p protocol, and unix sockets

tunnels are invoked like atoms, but have scope like control flow end scope closes the tunnel

note the form must always be of a form which is "tunnel-able" i.e. Files, sockets, etc

### subroutines for tunnels

#### create a new tunnel

«field», … `«tunnel-able form»` tunnel

open communication

tunnel args, … `attach` bool tunnel

close communication

tunnel `clunk` bool tunnel

cancels long operation and dumps whatever is in buffer

tunnel `flush` bool tunnel

opens a tunnel for doing operations on

tunnel resource mode `open` bool tunnel

creates the object from the database graph/file from file structure

tunnel resource `create` bool tunnel

reads from a tunnel

tunnel resource `read` «form» tunnel

writes to a tunnel, gets response from endpoint

tunnel resource data `write` bool tunnel

removes the object from the database graph/file from file structure

tunnel resource `remove` bool tunnel

returns the status of the file/resource

tunnel resource `stat` tunnel «status data» 

returns the version code for the connected tunnel, returns of version info

tunnel `version` (list) tunnel

moves around the filesystem or through the graph

tunnel "path_or_endpoint" `walk` bool tunnel


#### example

```
"echo_tunnel" "user" "auth" "http://example.com" url attach set ! create a new tunnel called "echo tunnel" and attach it to the resource
"hello world" "/some/rest/echo" echo_tunnel open pop write ! open the endpoint and read write the "hello world" to it
echo_tunnel read std write ! syncronously read in the data echoed back from the endpoint and print it to stdout
flush
clunk pop 
"echo_tunnel" del 
```

in "terminal mode" the default tunnel is std

in "web mode" the default tunnels are log, info, trace, warn, error, but note these are all special tunnels which only accept write commands

## subroutines

```
{
 «instructions»
}
```

- Built in subroutines
  - sort
  - filter
  - trig functions
  - calc functions
  - statistical functions

## Control flow

### loops

runs the subroutine infinitely until it breaks or panics

{ «body» } `loop` -

runs the subroutine a given number of times

«some numeric value» { «body» } `repeat` -

runs the subroutine a given number of times

## Libraries and “includes”

In most languages the include or use statements get libraries which link to other files and so on. This quickly gets confusing and so requires package managers and installers, etc.
The other way to do this would be to just specifically “name” the paths using a tunnel and import it. You can even use localization tokens to create config files.
Since everything is lazily compiled jit anyways it (in theory) doesn't hurt performance much

"https://raw.githubusercontent.com/some_user/some_library/some_file.zwl" `import`

"./some_local_file.zwl" `import`


## Universe

All forms and complications exist within the universe.
The universe can be thought of as the "global" namespace in an object oriented language or as the kernel for the "atom processes" to exist in.
a "main" space should be created that invokes the required startup atoms of the syntax.
in kOS this actually *is* the kernel layer

## GUI

The GUI is inspired by PicoLisp and Electron, using a web browser engine to render the GUI including 3D stuff like webgl.
Most html elements have an analogous form in *zwl*: Tables, lists, links, buttons, input boxes, etc.
In kOS these are replaces by its own version of these forms.

These of course can be wrapped in your own implementations. The idea is that on *zwls* side all UI is unified by forms but also is interoperable with HTML, templating engines, or gui libraries

## Concurrency

As in elixir there are as many schedulers as there are cores for your cpu
Like in CM and real time micro architecture systems like QNX tasks are scheduled based on priority and must stay within a time limit or it will be “punished” into a lower priority
Threading in *zwl* are split up into tasks (which take input) and daemons (which take no input)
Tasks are spawned whereas daemons are summoned
Message passing can be achieved by using tunnels.

probably should take concurrency stuff from golang; its very nice


# Appendicies

## Modern programming languages in the 21st century usually have need for the following requirements

### Data

- describing data
  - numeric
  - string
  - logical
  - complex
    - point
    - edge
    - color
    - many more
  - qualitative
    - sentiment analysis
    - more...
  - measurements
    - tons of these...

### Inputing data

- stdio
- program args
- command line
- reading from other source
- gui
  - input boxes
  - forms
  - many others

### Storing descriptions of data

- internal
  - graph
    - array
    - list
    - set
  - map
- external
  - database
    - local
    - cloud
- writing data
  - stdout
  - stderr
  - writing to other source
    - file
    - tape
    - socket

### Manipulating data

- algorithms
  - sort
  - filter
  - math functions
  - trigonometric
  - statistics
  - calculus
  - many more
- Validating data
  - business rules
  - constraints
  - formulas

### Displaying data

  - objects
    - 3d models
    - 2d models
  - graphs
  - tables
  - infographics
  - written output
    - ai generated text

### System/World Objects

- Viewing objects in nth dimensional space
- Animations
  - moving the objects in space
  - manipulating objects
- Interaction from user input on objects in space
- Creating

### Communication

- Sending and receiving data
  - protocols
- Controlling real world objects
  - embedded programs
  - web programs
  - mobile
  - desktop
  - smart devices (IOT)
- Encryption
  - hashing
  - keys
  - more ...

### Meta

- documentation
- tutorials
- generating objects automatically like 

### Data Description

- windowing system
  - window
  - terminal
  - web browser
- form of the object (description)
  - version number
  - fields
    - forms
    - what dimensional object
    - unit form / measurements
  - display
    - What the UI default should be
    - type of display
    - position in space
  - user controls
  - validations
  - communications
- CRUD
  - create
  - read
  - update
  - delete


## Measurement

- forms
  - time
    - unit
      - seconds (s)
    - subforms
      - date
        - Default is ISO 8601
  - length
    - unit
      - metre (m)
    - subforms
      - angle
        - radian (rad)
  - mass
    - unit
      - kilogram (kg)
  - electric current
    - unit
      - ampere (a)
  - temperature
    - unit
      - kelvin (K)
  - amount of substance
    - unit
      - mol (mol)
  - luminous intensity
    - unit
      - candela (candela)