tisp.7.md (8087B)
1 # tisp \- tiny lisp 2 3 [](https://travis-ci.org/edvb/tisp) 4 5 Tisp is a tiny, terse, and transparent lisp programming language designed to be lightweight 6 and easy to embedded in other programs. Simply drop the `tisp.c` and `tisp.h` 7 files into your project in order to use the necessary functions for your 8 program. An example command line interpreter is provided in `main.c`. Tisp is a 9 single value name language (lisp-1) which tries to be unambiguous and focus 10 on simplicity. Much of the language is defined with Tisp itself leaving the C 11 code as short as possible. 12 13 The language is still in active development and not yet stable. Until the `v1.0` release expect 14 non-backwards compatible changes in minor releases. 15 16 ## Language 17 18 Tisp is mainly based off of scheme, with minor features borrowed from other 19 lisps and scripting languages. 20 21 ### General 22 23 #### Comments 24 25 Single line comments with a semicolon, **eg** `(cons 1 2) ; ingnored by tisp until new line`. 26 27 ### Types 28 29 #### Nil 30 31 Nil, null, empty, or false, represented as an empty list, **eg** `()`, `nil` `false`. 32 33 #### Integers 34 35 Whole real numbers, positive or negative with optional `+` or `-` prefixes 36 repressively. Also supports scientific notation with a capital or lowercase 37 `e`. The exponent needs to be an positive integer, it can also be negative but 38 that would just round to zero. **eg** `1`, `-48`, `+837e4`, `3E-2`. 39 40 #### Decimals 41 42 Floating point numbers, also know as decimals, are numbers followed by a period 43 and an optional mantissa. Like integers they can be positive or negative with 44 scientific notation, but still need an integer as an exponent. **eg** `1.`, 45 `+3.14`, `-43.00`, `800.001e-3`. 46 47 #### Rationals 48 49 Fraction type, a ratio of two integers. Similar rules apply for numerator and 50 dominator as integers (real positive or negative), except for scientific 51 notation. Will simplify fraction where possible, and will through error 52 on division by zero. **eg** `1/2`, `4/3` `-1/2`, `01/-30`, `-6/-3`. 53 54 #### Strings 55 56 String of characters contained inside two double quotes. Any character is 57 valid, including actual newlines, execpt for double quotes and backspace which 58 need to be escaped as `\"` and `\\` respectively. Newlines and tabs can also be 59 escaped with `\n` and `\t` **eg** `"foo"`, `"foo bar"`, `"string \"quoted\""`, 60 `"C:\\windows\\path"` `\twhite\n\tspace`. 61 62 #### Symbols 63 64 Case sensitive symbols which are evaluated as variable names. Supports lower and 65 upper case letters, numbers, as well as the characters `_+-*/\\^=<>!?@#$%&~`. 66 First character can not be a number, if the first character is a `+` or `-` 67 then the second digit cannot be a number either. Unlike all the previously 68 listed types, symbols are not self evaluating, but instead return the value 69 they are defined to. Throws an error if a symbol is evaluated without it being 70 previously assigned a value. **eg** `foo`, `foo-bar`, `cat9`, `+`, `>=`, 71 `nil?`. 72 73 #### Lists 74 75 Lists composed of one or more elements of any type, including lists themselves. 76 Expressed with surrounding parentheses and each element is separated by 77 whitespace. When evaluated the procedure found at the first element is run with 78 the rest of the elements as arguments. Technically list is not a type, but 79 simply a nil-terminated chain of nested pairs. A pair is a group of two and 80 only two elements, normally represented as `(a . b)`, with `a` being the first 81 element (car/first) and `b` being the second element (cdr/rest). For example 82 `(a b c)` is equivilent to `(a . (b . (c . ())))`, but it is often easier to 83 express them the first way syntactically. To create an improper list (not 84 nil-terminated list) the dot notation can be used, `(1 2 3 . 4)`. 85 86 #### Functions 87 88 Lambda functions created within Tisp itself. Called using list syntax where the 89 first element is the function name and any proceeding elements are the 90 arguments to be evaluated. For example `(cadr '(1 2 3))` is a list of elements 91 `cadr` and `'(1 2 3)`. It calls the function `cadr` which returns the 2nd 92 element of the argument given, in this case a list of size 3, which returns 93 `2`. **eg** `list`, `not`, `apply`, `map`, `root`, `sqrt`, `print` 94 95 #### Primitives 96 97 Procedures built in to the language written in C. Called like regular 98 functions, see primitives section for more details. **eg** `car`, `cond`, 99 `def`, `write`, `+` 100 101 #### Macros 102 103 Like lambda functions macros are defined within Tisp and are called in a 104 similar fashion. However unlike functions and primitives the arguments are not 105 evaluated before being given to the macro, and the output of a macro is 106 only evaluated at the end. This means instead of taking in values and returning 107 values, macros take in code and return code, allowing you to extend the 108 language at compile time. **eg** `if`, `and`, `or`, `let`, `assert` 109 110 ### Built-ins 111 112 Built in primitives written in C included by default. 113 114 #### car 115 116 Returns first element of given list 117 118 #### cdr 119 120 Return rest of the given list, either just the second element if it is a pair, 121 or another list with the first element removed. 122 123 #### cons 124 125 Creates a new pair with the two given arguments, first one as the car, second 126 as the cdr. Can be chained together to create a list if ending with `nil`. 127 128 #### quote 129 130 Returns the given argument unevaluated. 131 132 #### Void 133 134 Returns nothing. Used to insert a void type in a list or force a function not 135 to return anything. 136 137 #### eval 138 139 Evaluates the expression given, can be dangerous to use in practice. In general 140 `apply` should be used instead. 141 142 #### = 143 144 Tests if multiple values are all equal. Returns `nil` if any are not, and `t` 145 otherwise. 146 147 #### cond 148 149 Evaluates each expression if the given condition corresponding to it is true. 150 Runs through all arguments, each is a list with the first element as the 151 condition which needs to be `t` after evaluated, and the rest of the list is 152 the body to be run if and only if the condition is met. Used for if/elseif/else 153 statements found in C-like languages and `if`,`when`,`unless`,`switch` macros 154 in Tisp. 155 156 #### typeof 157 158 Returns a string stating the given argument's type. Used to create `type?` 159 individual functions. 160 161 #### lambda 162 163 Creates function, first argument is a list of elements representing the symbol 164 name for any arguments of the new function. Rest of the arguments are code to 165 be run with the supplied arguments. 166 167 #### macro 168 169 Similar to lambda, creates anonymous macro with first argument as macro's 170 argument list and rest as macro's body. 171 172 #### def 173 174 Create variable with the name of the first argument, with the value of the 175 second. If name given is a list use the first element of this list as a new 176 functions name and rest of list as its arguments. If only variable name is 177 given make it self evaluating. 178 179 #### set! 180 181 Change the value of the of the variable given by the first argument to the 182 second argument. Errors if variable is not defined before. 183 184 #### load 185 186 Loads the library given as a string. 187 188 #### error 189 190 Throw error, print message given by second argument string with the first 191 argument being a symbol of the function throwing the error. 192 193 #### version 194 195 Return string of Tisp's version number. 196 197 ### Differences From Other Lisps 198 199 In Tisp there are no boolean types, much like common lisp, true is represented 200 by the self evaluating symbol `t` and false is nil, represented as `()`, an 201 empty list. `nil` and `false` are also mapped to `()`. 202 203 Tisp also only has one builtin equality primitive, `=`, which tests integers, 204 symbols, strings, and objects which occupy the same space in memory, such as 205 primitives. 206 207 Symbols are case sensitive, unlike many other older lisps, in order to better 208 interface with modern languages. 209 210 Tisp is single value named, so procedures share the same namespace as 211 variables, removing the need for common lisp's `defunc` vs `defvar`, `let` vs 212 `flet`, and redundant syntax for getting the function from a symbol. 213 214 ## Author 215 216 Ed van Bruggen <ed@edryd.org> 217 218 ## See Also 219 220 tisp(1) 221 tsp(1) 222 223 See project at <https://edryd.org/projects/tisp> 224 225 View source code at <https://git.edryd.org/tisp> 226 227 ## License 228 229 zlib License