diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/thac.1 | 53 | ||||
| -rw-r--r-- | doc/thalatta.5 | 299 |
2 files changed, 352 insertions, 0 deletions
diff --git a/doc/thac.1 b/doc/thac.1 new file mode 100644 index 0000000..1da5f4c --- /dev/null +++ b/doc/thac.1 @@ -0,0 +1,53 @@ +.Dd April 5, 2026 +.Dt THAC 1 +.Os +. +.Sh NAME +.Nm thac +.Nd thalatta compiler +. +.Sh SYNOPSIS +.Nm +.Ar file +. +.Sh DESCRIPTION +.Nm +implements a procedural graph description language. +It evaluates +.Ar file +and then emits resulting graph in the following format: +.Do +.Va prop0 +.Va ... +.Va propN +| +.Va out0 +.Va ... +.Va outM +.Dc , +where +.Bl -dash -width Ds -compact +.It +.Va N , +.Va M +are nonnegative integers +.It +.Va X +in +.Va propX +is an integer +.It +.Va X +in +.Va outX +is a nonnegative integer +.El +. +.Sh RETURN VALUES +.Ex -std +. +.Sh SEE ALSO +.Xr thalatta 5 +. +.Sh AUTHORS +.An Nakidai Perumenei Aq Mt nakidai@disroot.org diff --git a/doc/thalatta.5 b/doc/thalatta.5 new file mode 100644 index 0000000..2cc35b7 --- /dev/null +++ b/doc/thalatta.5 @@ -0,0 +1,299 @@ +.Dd April 5, 2026 +.Dt THALATTA 5 +.Os +. +.Sh NAME +.Nm thalatta +.Nd procedural graph description language +. +.Sh DESCRIPTION +.Nm +is a language used to generate attributed digraphs. +It is intended to be minimalist, +yet provides enough syntax for convenient graph construction. +.Nm +has C-like syntax, +but introduces some new features as well, +while removing unnecessary ones for graph context. +This manual shows only where +.Nm +differs from C. +. +.Ss Values +There are only 3 types in +.Nm : +arrays, integers, and nil. +. +.Pp +Arrays are constant: +a new one is allocated on operations such as assignment, +concatenation etc. +. +.Pp +Integers store not only user-defined numbers, +but also node and module identifiers used by an implementation. +These identifiers are used by the implementation +and should not be edited by the programmer. +. +.Pp +Nil type is the one that does not hold anything. +It can be used as a placeholder. +.Nm +has a predefined variable +.Dv nil +of the type of the same name. +. +.Ss Operations +.Nm +has operations very like in C, +excluding function calls, +structures, +and some others. +Instead introduces some new ones: +.Bl -tag -width Ds +.It Connecting +.Nm +is a graph description language. +The +.Ic <- +operator is used to connect a graph. +Its precedencence is like of an addition. +It creates a connection from right to left, +returning the left operand, so +.Bd -literal -offset indent -compact +a <- b <- c; +.Ed +connects both b and c to a, +not b to a and c to b. +. +.Pp +Connecting a node to an array +means connecting it all the cells from the array. +Connecting array to array is possible only if they are isomorphic, +i.e., +they are of the same length, +and all subarrays are of the same length recursively, +if applicable. +. +.It Generation +.Nm +lacks array initializers like in C. +Instead, +there is a prefix operator +.Ic Bq Va expr , +where +.Va expr +must be an integer. +This will allocate an array +of size +.Va expr . +For each array cell of depth n +there is a variable starting with @ +followed by an nth letter of the alphabet +storing current depth's index. +. +.Pp +For example, +this code: +.Bd -literal -offset indent -compact +[2][3]node(@a, @b); +.Ed +. +.Pp +generates 4 nodes with properties as in binary count: +.Bd -literal -offset indent -compact +0 0 | +0 1 | +0 2 | +1 0 | +1 1 | +1 2 | +.Ed +. +.It Slicing +Besides simple indexing, +.Nm +has a postfix operator +.Ic Bq Va l Ic : Va r +that returns a slice of given array +from +.Va l +inclusive to +.Va r +non inclusive. +Both bounds are clamped +to the array limits. +. +.It Concatenation +The +.Ic >< +operator is used to concatenate 2 arrays. +Its precedence is like of a multiplication. +. +.It Exponentiation +Uses +.Ic ** +operator, +is done before multiplication and right-associative. +.El +. +.Pp +.Nm +has also the prefix operator +.Ic len +to get an array length, +and the prefix operator +.Ic assert +aborting the execution +if its argument evaluates to zero, +and returning it otherwise. +. +.Ss Nodes +Nodes are created using the following syntax: +.Bd -literal -offset indent -compact +node(prop1, prop2); +.Ed +where properties are numbers. +This will return a number \(em +a unique node identifier. +. +.Ss Foreach +The +.Ic foreach +construct is used to iterate over elements of an array. +It recursively walks through its argument, +for each cell executing its body with variables +.Va @0 +.Va @1 +\&... +set just like the generation operator does. +In addition, +it sets the +.Va @ +variable to the current element. +. +.Pp +This code ensures that every number in array +.Va arr +is greater than zero: +.Bd -literal -offset indent +foreach (arr) { + assert(@ > 0); +} +.Ed +. +.Ss Modules +Instead of functions, +.Nm +has modules. +A module with parameters +.Ar a , +.Ar b +can be defined like that: +.Bd -literal -offset indent +mod (a, b) { } +.Ed +It is possible to assign this +to a variable. +. +.Pp +Then, +to use this module later, +there is +.Ic with +statement, +that first evaluates the module +and then executes its body, +with parent scope set to the scope +of the module. +. +.Pp +This code tests whether the variable x is positive, +though in somewhat weird way to show the module usage: +.Bd -literal -offset indent +foo = mod(a) { + b = a; +} + +with foo(x) { + assert(b > 0); +} +.Ed +. +.Sh SYNTAX +This is the syntax of +.Nm +expressed in ABNF: +.Bd -literal -indent offset +code = *(stmt) +stmt = comp / for / foreach / if / with / expr ";" / break / continue +continue = "continue" ";" +break = "break" ";" +with = "with" expr "(" [*(expr ",") expr] ")" stmt +if = "if" "(" expr ")" stmt ["else" stmt] +foreach = "foreach" "(" expr ")" stmt +for = "for" "(" [expr] ";" [expr] ";" [expr] ")" stmt +expr-assign-oper =/ "|=" / "^=" / "=" / ">>=" / "<<=" / "%=" +expr-assign-oper = "+=" / "-=" / "*=" / "/=" / "%=" / "&=" +expr-assign = expr-cond [expr-assign-oper expr-assign] +expr-cond = expr-or ? expr : expr-cond +expr-pref = expr-post / ("assert" / "len" / "~" / "!" / "--" / "++") expr-pref +expr-post = expr-primary *("--" / "++" / "[" expr [":" expr] "]") +expr-mod = "mod" "(" [*(id ",") id] ")" comp +expr-node = "node" "(" [*(expr ",") expr] ")" +expr-primary = NUMBER / id / "nil" / expr-node / expr-mod / "(" expr ")" +comp = "{" *(stmt) "}" +expr = expr-assign +.Ed +. +.Sh EXAMPLES +This snippet creates a graph of a CLA adder: +.Bd -literal -offset indent +and = 0; +xor = 1; + +add = mod(a, b, c) +{ + assert(len(a) == len(b)); + l = len(a); + out = [l]node(xor); + { + p = [l]node(xor) <- a <- b; + g = [l]node(and) <- a <- b; + out <- p; + + foreach (out) + { + @ <- (node(and) <- p[0:@0] <- c); + for (i = 0; i < @0; ++i) + @ <- (node(and) <- p[i+1:@0] <- g[i]); + } + } +}; + +first = [8]node(xor, 0); +second = [8]node(xor, 1); +carry = node(xor, 2); +with add(first, second, carry) { } +.Ed +. +.Sh SEE ALSO +.Xr thac 1 +. +.Rs +.%A B. W. Kernighan +.%A D. M. Ritchie +.%D 1978 +.%B The C Programming Language +.Re +. +.Rs +.%A D. Crocker +.%A P. Overell +.%D January 2008 +.%R RFC 5234 +.%T Augmented BNF for Syntax Specifications: ABNF +.Re +. +.Sh AUTHORS +.An Nakidai Perumenei Aq Mt nakidai@disroot.org |