Pages

Definition

Objects and abstractions

Syntax

Settings and modifiers

Blog

Motivation

Use cases and requirements

Cheat sheets

Quick reference

Screw long documentation, I’ll learn by example

Syntax

Alphabet

Symbol Meaning Example
: defines a pair a is an integer
a: int
= defines a pair hostname is “google.com”
hostname = google.com
/ defines paths, database names, table names, or partitions objects inside storage db’s database my_db’s table messages with partition key request.date:
db: storage
db/my_db/messages/ partition[messagedate_pkey: request.date]
() and . parentheses define hierarchy, and dot is used to access it  
[] brackets define complex types, or add meta-information to an object that they follow. Syntax:
[modifierValue]
[modifierType: modifierValue]
[modifierType: modifierValue1, modifierValue2]
modifierType[modifierValue]
modifierType[modifierSubtype:modifierValue]		 #a is a stream of messages in json format. They are coming through a HTTP Websocket.
> a: stream [format:json] source[http: websocket]
> < = strict comparisons that define domain of values age is a positive int
age: int [a >= 0]
>~ <~ ~ ~= fuzzy comparisons that define reasonable domain of values (typical values) age is typically between 18 and 30
a: int [18 ~< a ~< 30]
~~ order of magnitude size ~~ 10Gb
>–>
<–<		 data flow arrows a writes to storage b in batch
a —-> b
_ Meta-commands (include, import, …)  
! Deploy mode  
^ Version or version draft (=proposal)  
# Docstring  
\ Distribution  
“x” treat x as a literal  
$x treat x as a reference  
@t at moment x  
x’ change/new value of x  

modifierSubtype, modifierType, pieces of full object qualifier (. path, like a.b.c) can be omitted if they can be resolved unambiguously. " and $ can be skipped as well. Values will be

Basic data types

int

  • B Billions
  • M Millions
  • K Thousands

float

str str.nonempty str.identifier (valid program variable name)

str.email str.password str.phone str.username

str.url str.hostname str.filename

str.json str.xml str.base64

blob blob.picture blob.sound blob.model

timestamp date datetime timespan

Basic units

ms milliseconds
s seconds
m minutes
h hours
d days
w weeks
mon months

size b|byte Kb, Mb, Gb, Tb

Complex types

  • List[x], Map[x, y], Array[x] are complex data types. They wrap around x, adding extra properties to the field_name (field_name.len for all complex types; and field_name.keys/field_name.values for Map).

  • embedded[SchemaName: fields1, fieldsN] includes part of another schema into that one. If no fields are specified, then all are used. Asterisk * in the field name is used as a placeholder. It define a place where the original variable’s name is placed (if there is no asterisk, embedded schema’s field names are appended to the field_name).
    • For example, user_*: Embedded[User: name, age] becomes user_name: User.name , user_age: User.age
  • enum[EnumName: value1, value2, ... valueN] defines enum EnumName with a list of possible values.

Modifiers

Modifiers supply with meta-information. They look like

  • modifierType[modifierSubtype: modifierValue]
    • or modifierType[modifierSubtype: modifierValue, sub2: value2, sub3: value3a, value3b, value3c]
    • or modifierType[modifierSubtype: value1, value2, value3]
  • [modifierSubtype: modifierValue]
    • or [modifierSubtype: value1, value2, value3]
  • modifierType[modifierValue]
    • ormodifierType[value1, value2, value3]
  • or just [modifierValue]

They go right after the object definition:

field_name: fieldtype [modifierSubtype: modifierValue]

or

appname: app [modifierSubtype: modifierValue] ( ... )

they often replace =. Example above can be rewritten as

appname: app (
    modifierSubtype: modifierValue
    ...
)

Conditions

For each property, we may use modifiers to specify some conditions.

  • > < =, to specify valid ranges
  • >~ ~< =~ to specify typical ranges (reasonable bounds)
  • ~~ to define order of magnitude or asymptotic line
  • = or =~ to define expected value or typical value
  • start.. , ..end, start..end to define ranges, for example 0..100
  • % to specify divisibility. “a is ranges from 0 to 1000 with step 10” is written as a: int [0..1000, a % 10]
  • len, start.. end when applied to strings, specify string length or substrings (which can then be used in conditions)

Template commands

_as: QWE; then _.x means QWE.x

_| resolved _include: <localfile>

_import_FORMAT: git+<git url>/path^X. X branch or hash or release. FORMAT is lil, docker , docker-compose, …

_code: path/sourcefile.ext#Lnum [arg1: sourcearg1] [arg2: sourcearg2] [connclass: sourceclassname]

_uml (...) defines internal structure, class or activity diagrams in plant uml format.