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"

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

• 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 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)