zongors-universe-machine/SPECIFICATION.MD

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, like var'aq, uiua, and TIS-100 assembly 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