# _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"
- the "constructor" of it is
  - string for the name of the form
  - 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
  - the list of allowed forms that can be used as input
  - a list containing the data of that form

"form-name" «dimensions» «unit» «display» «position» («list» «of» «allowed» «input» «forms» …) («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

- `true` bool

### false

- `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.

( «item» «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

"«name of the value [no spaces]»" «value» `set` -

#### delete from node's map

«name-of-the-item» `del`

#### adds the top values on the stack

num num `add` num (of same type)

#### subtracts the top values on the stack

num num `sub` num (of same type)

#### multiplys the top values on the stack

num num `mul` num (of same type)

#### divides the top values on the stack

num num `div` num (of same type)

#### does a n'th power the top values on the stack

num num `pow` num (of same type)

#### returns the divisor of the top values on the stack

num num `mod` num (of same type)

#### checks if the top values on the stack are equal

val val `eq` bool

#### checks if the top values on the stack are not equal

val val `ne` bool

#### checks if the top values on the stack are equal

val val `not` bool

#### does an and operation on the top of the stack

bool bool `and` bool

#### does an or operation on the top of the stack

bool bool `or` bool

#### does an not-or operation on the top of the stack

bool bool `nor` bool

#### does an not-and operation on the top of the stack

bool bool `nand` bool

#### does an exclusive or operation on the top of the stack

bool bool `xor` bool

#### does an bitwise and operation on the top of the stack

val val `band` val (of same type)

#### does an bitwise or operation on the top of the stack

val val `bor` val (of same type)

#### does an bitwise nor operation on the top of the stack

val val `bnor` val (of same type)

#### does an bitwise xor operation on the top of the stack

val val `bxor` val (of same type)

#### does an bitwise shift left

val num `sll` val (of same type)

#### does an bitwise shift right

val num `srl` val (of same type)

#### checks the form of the value on top of the stack

«value» «form» `?` bool

## 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

args, … `attach` bool tunnel

#### close communication

tunnel `clunk` bool

#### 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

### built in tunnleable forms

#### file

A file that exists on the local filesystem

#### http

A file or data endpoint that exists on the internet or other network using the http protocol

#### https

A file or data endpoint that exists on the internet or other network using the https protocol

#### 9p

A file or data endpoint that exists on the internet or other network using the 9p protocol

## subroutines

{ «instructions» `}`

- Subroutines in stdlib
  - sort
  - filter
  - trig functions
  - calc functions
  - statistical functions
  - I/O
  - networking
  - more...

## 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 for each element on the stack

{ «body» } `map` ?

## 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.

The import subroutine takes in a tunnel and evaluates the contents in the node. import the same as creating a tunnel, reading the contents, and evaluating the response.

"«string of resource location»" «tunnel-able form» `import` -

For example:

```
"./some_local_file.zwl" file import                                                  ! imports a local file
"/lib/stdlib.zwl" file import                                                        ! imports the standard library
"/some_user/some_library/some_file.zwl" "raw.githubusercontent.com" https import     ! imports the contents of this url
```

## 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

### Data

- describing data
  - numeric
  - string
  - logical
  - complex
    - point
    - edge
    - color
    - many more
  - qualitative
    - sentiment analysis
    - more...
  - measurements
    - 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)
    - more...

### 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
- metaprogramming
  - macros
  - generating objects automatically

### 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