1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
.TH PRECEDENT 1 "23 Feb 21" "Precedent version 0.1"
.SH NAME
precedent \- simple interpreted language
.SH SYNOPSIS
\fBprecedent\fP <file> [--visualize] [--debug] [--version] [--help]
.SH DESCRIPTION
Precedent is an interpreted language. The syntax is extremely simple,
which lends to writing in a functional paradigm. However, precedent also
supports imperative programming, with variable scoping and side-effects.
Precedent supports integers, floats, and strings, with basic functions
to manipulate each. Precedent has a simple pre-processor supporting
include statements, so libraries may be written to re-use code.
Precedent runs in three stages: preprocess, parse, eval/exec.
.SH OPTIONS
\fB--help\fP
\-\- Displays usage info.
\fB--version\fP
\-\- Displays version info, and license information.
\fB--visualize\fP
\-\- Displays the the program structure before execution.
\fB--debug\fP
\-\- Writes additional debug information.
.SH DICHOTOMY
Everything in precedent is a symbol. Every symbol is either a key or literal.
A literal may be an integer, a float, or a string, and is self-evaluating.
A key exists in some scope, and points to some symbol. There are default ("internal")
keys, and keys created with store(). A key may accept parameters, making it a function.
.SH SYNTAX
In the documentation to follow, square brackets are used to indicate blocks of precedent code. They are NOT part of the code--only for documentation readability.
Spaces, tabs, newlines, and other forms of whitespace are ignored.
A literal value is either a number or wrapped in quotation marks. The following
are examples of literal values: [ 123, "hello world", 9.81 ]. A key without arguments
is simply stated as a word. The following are examples of key references:
[ myVar, arg0 ]. A key reference may have any number of arguments, which may be
literals or key references. The following are examples of key references with arguments:
[ print("hello world"), print(myVar), print(eq(1, 2)) ]. Literals and keys may be separated by commas, semicolons, or spaces, to taste.
.SH PREPROCESSOR
The preprocessor is an extremely simple parser that runs before the file is passed to the main parser.
The preprocessor supports two directives: include, and guarded include.
Include is invoked as follows: [ &toinclude.pcdt ]. The file specified
is then prepended to the current file.
The file path is relative to the file that the preprocessor is evaluating. That is to say, a file's include statements should specify the path of the file they wish to include, relative to their own location.
Guarded include is invoked as follows: [ @toinclude.pcdt ]. It is exactly
equivalent to a regular include, except that any given file will only be
included a single time. Suppose there is some library file math.pcdt. If a file
includes two files, which each include math.pcdt, guarded include will prependonly one copy of math.pcdt to the beginning of the preprocessor output. Guarded include is more performant, and prevents overfilling the hashtable. Use it unless
you have a very good reason not to.
.SH DETAILS
When a function defined by ref() is called as, e.g., myFunc(1, 1), its arguments (in this case, 1 and 1) are passed to the called function as arg0 and arg1. This implementation is subject to change.
Logical functions treat all non-zero integer values as TRUE, and 0 as FALSE. Passing a float or a string to such a function will usually result in an error. Some logical functions short-circuit, meaning that they will cease evaluation as soon as their condition can no longer be met.
For example, if the first argument to all() is FALSE, it will not evaluate the rest of its arguments.
.SH FUNCTIONS
\fBDATA STORAGE AND RETRIEVAL\fP
\fBref()\fP
\-\- Returns a pointer to its first argument, not evaluating it.
\fBeval()\fP
\-\- Evaluates its first argument, passing the the rest of its arguments as arg0, arg1... etc. Essentially undoes ref().
\fBstore()\fP
\-\- Stores the evaluation of its first argument under the name specified by the (string) evaluation of its second argument. Use with ref() to store functions, or without to store variables.
\fBupdate()\fP
\-\- Stores the evaluation of its first argument under the name specified by the (string) evaluation of its second argument, in the same manner as store(). Update() differs from store when the key is not found in the local scope. In this case, update() searches upwards for the first scope containing the key, and overwrites its value.
\fBBOOLEAN LOGIC\fP
\fBeq()\fP
\-\- Evaluates all of its arguments. If they are all equivalent, returns TRUE. Otherwise, returns FALSE. Can accept ints, floats, or strings. Strings cannot be mixed with floats or ints.
\fBany()\fP
\-\- Evaluates all of its arguments. If any are not FALSE, returns TRUE. Otherwise, returns FALSE. Equivalent to the logical operator OR. Short-circuits.
\fBall()\fP
\-\- Evaluates all of its arguments. If all are not FALSE, returns TRUE. Otherwise, returns FALSE. Equivalent to the logical operator AND. Short-circuits.
\fBone()\fP
\-\- Evaluates all of its arguments. If exactly one argument is not FALSE, returns TRUE. Otherwise, returns FALSE. Equivalent to the logical operator XOR. Short-circuits.
\fBnone()\fP
\-\- Evaluates all of its arguments. If none are TRUE, returns TRUE. Otherwise, returns FALSE. Short-circuits.
\fBCONTROL FLOW\fP
\fBroot() OR ()\fP
\-\- Executes all arguments. Returns the evaluation of the last symbol. Used to define a function.
\fBif()\fP
\-\- If its first argument is TRUE, evaluates the rest of its arguments.
\fBwhile()\fP
\-\- If its first argument is TRUE, evaluates the rest of its arguments. Then, if its first argument is still TRUE, evaluates the rest of its arguments again. Repeats until its first argument is FALSE.
\fBARITHMETIC\fP
\fBsum()\fP
\-\- Evaluates all its arguments and returns the sum. If any argument is a float, returns a float. Otherwise, returns an int.
\fBsub()\fP
\-\- Evaluates all its arguments. Subtracts every argument after the first from the first. Returns the result, which is a float if any arguments were floats, or an int if all arguments were ints.
\fBI/O\fP
\fBprint()\fP
\-\- Evaluates its arguments and writes each to STDOUT. Writes a newline after all its arguments.
\fBinput()\fP
\-\- Reads from STDIN until the next newline character. Returns everything up to the newline. If it is passed a string, writes it to STDOUT as a prompt.
.SH AUTHOR
Developed and maintained by Kai Stevenson.
See git.aberrantflux.xyz/precedent.git for the latest version
of the software.
.SH "SEE ALSO"
c(7)
|
