tisp

tiny lisp
git clone git://edryd.org/tisp
Log | Files | Refs | LICENSE

commit aef5b6d62dee16c203eabb68459e278c26bd5744
parent 29a33c3a314e669c58891066b0a1aa2bb5b879b3
Author: Ed van Bruggen <edvb@uw.edu>
Date:   Wed, 24 Mar 2021 18:13:43 -0700

Split man page into CLI and language pages

Modify man page generation in Makefile to take list of markdown files

Diffstat:
Makefile | 10+++++++---
README.md | 4++--
doc/tisp.1 | 143++++---------------------------------------------------------------------------
doc/tisp.1.md | 219+++----------------------------------------------------------------------------
doc/tisp.7 | 161+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/tisp.7.md | 229+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 412 insertions(+), 354 deletions(-)

diff --git a/Makefile b/Makefile @@ -14,6 +14,8 @@ TIB = tib/math.c tib/io.c tib/os.c tib/string.c OBJ = $(SRC:.c=.o) $(TIB:.c=.o) LIB = tib/libtibmath.so tib/libtibio.so TSP = tib/core.tsp tib/io.tsp tib/math.tsp tib/doc.tsp tib/repl.tsp +DOC = doc/tisp.1.md doc/tisp.7.md +MAN = $(DOC:.md=) all: options $(EXE) @@ -98,9 +100,11 @@ test: $(OBJ) $(LIB) test.o @$(CC) -o test tisp.o $(TIB:.c=.o) test.o $(LDFLAGS) @./test -man: $(EXE) - @echo updating man page doc/$(EXE).1 +man: $(MAN) + +$(MAN): $(DOC) $(EXE) + @echo updating man page $@ @markman -nCD -t TISP -V "$(EXE) $(VERSION)" -d "`date '+%B %Y'`" \ - -s "`./$(EXE) -h 2>&1 | cut -d' ' -f2-`" doc/$(EXE).1.md > doc/$(EXE).1 + -s "`./$(EXE) -h 2>&1 | cut -d' ' -f2-`" $@.md > $@ .PHONY: all options clean dist install uninstall test man diff --git a/README.md b/README.md @@ -1 +1 @@ -doc/tisp.1.md- \ No newline at end of file +doc/tisp.7.md+ \ No newline at end of file diff --git a/doc/tisp.1 b/doc/tisp.1 @@ -1,4 +1,4 @@ -.TH TISP 1 "September 2020" "tisp 0.0.0" +.TH TISP 1 "March 2021" "tisp 0.0.0" .PP .SH NAME tisp \- tiny lisp @@ -8,14 +8,9 @@ tisp [-hv] [-c COMMAND] [-] [FILE ...] .PP .SH DESCRIPTION .PP - -.PP -Tisp is a tiny, terse, and transparent lisp library designed to be lightweight and easy to embedded in other programs. Simply drop the 'tisp.c' and 'tisp.h' files into your project in order to use the necessary functions for your program. An example command line interpreter is provided in 'main.c'. Tisp is a single value name language (lisp-1) which tries to be unambiguous and focus on simplicity. Much of the language is defined with Tisp itself leaving the C code as short as possible. +Tisp programming language interpreter. Read and evaluate all files in order given, if file name is '-' read from 'stdin'. If no files are supplied launch REPL. .PP .SH OPTIONS -.PP -Read and evaluate all files in order given, if file name is '-' read from 'stdin'. If no files are supplied launch REPL. -.PP .TP \fB-c COMMAND\fP Read \fICOMMAND\fP as a line of Tisp code and print result @@ -36,7 +31,7 @@ Run the program from the command line to type a single command and press enter t .EX $ tisp -(cons 1 2) +> (cons 1 2) (1 . 2) .EE @@ -72,141 +67,15 @@ $ tisp -c "(reverse '(1/2 1/4 1/8 1/16))" .EE .RE -.SH LANGUAGE -.PP -Tisp is mainly based off of scheme, with minor features borrowed from other lisps and scripting languages. -.PP -.SS GENERAL -.TP -\fBComments\fP -Single line comments with a semicolon, \fBeg\fP '(cons 1 2) ; ingnored by tisp until new line'. -.PP -.SS TYPES -.TP -\fBNil\fP -Nil, null, empty, or false, represented as an empty list, \fBeg\fP '()', 'nil' 'false'. -.PP -.TP -\fBIntegers\fP -Whole real numbers, positive or negative with optional '+' or '-' prefixes repressively. Also supports scientific notation with a capital or lowercase 'e'. The exponent needs to be an positive integer, it can also be negative but that would just round to zero. \fBeg\fP '1', '-48', '+837e4', '3E-2'. -.PP -.TP -\fBDecimals\fP -Floating point numbers, also know as decimals, are numbers followed by a period and an optional mantissa. Like integers they can be positive or negative with scientific notation, but still need an integer as an exponent. \fBeg\fP '1.', '+3.14', '-43.00', '800.001e-3'. -.PP -.TP -\fBRationals\fP -Fraction type, a ratio of two integers. Similar rules apply for numerator and dominator as integers (real positive or negative), except for scientific notation. Will simplify fraction where possible, and will through error on division by zero. \fBeg\fP '1/2', '4/3' '-1/2', '01/-30', '-6/-3'. -.PP -.TP -\fBStrings\fP -String of characters contained inside two double quotes. Any character is valid, including actual newlines, execpt for double quotes and backspace which need to be escaped as '\"' and '\\' respectively. Newlines and tabs can also be escaped with '\n' and '\t' \fBeg\fP '"foo"', '"foo bar"', '"string \"quoted\""', '"C:\\windows\\path"' '\twhite\n\tspace'. -.PP -.TP -\fBSymbols\fP -Case sensitive symbols which are evaluated as variable names. Supports lower and upper case letters, numbers, as well as the characters '_+-*/\\^=<>!?@#$%&~'. First character can not be a number, if the first character is a '+' or '-' then the second digit cannot be a number either. Unlike all the previously listed types, symbols are not self evaluating, but instead return the value they are defined to. Throws an error if a symbol is evaluated without it being previously assigned a value. \fBeg\fP 'foo', 'foo-bar', 'cat9', '+', '>=', 'nil?'. -.PP -.TP -\fBLists\fP -Lists composed of one or more elements of any type, including lists themselves. Expressed with surrounding parentheses and each element is separated by whitespace. When evaluated the procedure found at the first element is run with the rest of the elements as arguments. Technically list is not a type, but simply a nil-terminated chain of nested pairs. A pair is a group of two and only two elements, normally represented as '(a . b)', with 'a' being the first element (car/first) and 'b' being the second element (cdr/rest). For example '(a b c)' is equivilent to '(a . (b . (c . ())))', but it is often easier to express them the first way syntactically. To create an improper list (not nil-terminated list) the dot notation can be used, '(1 2 3 . 4)'. -.PP -.TP -\fBFunctions\fP -Lambda functions created within Tisp itself. Called using list syntax where the first element is the function name and any proceeding elements are the arguments to be evaluated. For example '(cadr '(1 2 3))' is a list of elements 'cadr' and ''(1 2 3)'. It calls the function 'cadr' which returns the 2nd element of the argument given, in this case a list of size 3, which returns '2'. \fBeg\fP 'list', 'not', 'apply', 'map', 'root', 'sqrt', 'print' -.PP -.TP -\fBPrimitives\fP -Procedures built in to the language written in C. Called like regular functions, see primitives section for more details. \fBeg\fP 'car', 'cond', 'def', 'write', '+' -.PP -.TP -\fBMacros\fP -Like lambda functions macros are defined within Tisp and are called in a similar fashion. However unlike functions and primitives the arguments are not evaluated before being given to the macro, and the output of a macro is only evaluated at the end. This means instead of taking in values and returning values, macros take in code and return code, allowing you to extend the language at compile time. \fBeg\fP 'if', 'and', 'or', 'let', 'assert' -.PP -.SS BUILT-INS -.PP -Built in primitives written in C included by default. -.PP -.TP -\fBcar\fP -Returns first element of given list -.PP -.TP -\fBcdr\fP -Return rest of the given list, either just the second element if it is a pair, or another list with the first element removed. -.PP -.TP -\fBcons\fP -Creates a new pair with the two given arguments, first one as the car, second as the cdr. Can be chained together to create a list if ending with 'nil'. -.PP -.TP -\fBquote\fP -Returns the given argument unevaluated. -.PP -.TP -\fBvoid\fP -Returns nothing. Used to insert a void type in a list or force a function not to return anything. -.PP -.TP -\fBeval\fP -Evaluates the expression given, can be dangerous to use in practice. In general 'apply' should be used instead. -.PP -.TP -\fB=\fP -Tests if multiple values are all equal. Returns 'nil' if any are not, and 't' otherwise. -.PP -.TP -\fBcond\fP -Evaluates each expression if the given condition corresponding to it is true. Runs through all arguments, each is a list with the first element as the condition which needs to be 't' after evaluated, and the rest of the list is the body to be run if and only if the condition is met. Used for if/elseif/else statements found in C-like languages and 'if','when','unless','switch' macros in Tisp. -.PP -.TP -\fBtypeof\fP -Returns a string stating the given argument's type. Used to create 'type?' individual functions. -.PP -.TP -\fBlambda\fP -Creates function, first argument is a list of elements representing the symbol name for any arguments of the new function. Rest of the arguments are code to be run with the supplied arguments. -.PP -.TP -\fBmacro\fP -Similar to lambda, creates anonymous macro with first argument as macro's argument list and rest as macro's body. -.PP -.TP -\fBdef\fP -Create variable with the name of the first argument, with the value of the second. If name given is a list use the first element of this list as a new functions name and rest of list as its arguments. If only variable name is given make it self evaluating. -.PP -.TP -\fBset!\fP -Change the value of the of the variable given by the first argument to the second argument. Errors if variable is not defined before. -.PP -.TP -\fBload\fP -Loads the library given as a string. -.PP -.TP -\fBerror\fP -Throw error, print message given by second argument string with the first argument being a symbol of the function throwing the error. -.PP -.TP -\fBversion\fP -Return string of Tisp's version number. -.PP -.SS DIFFERENCES FROM OTHER LISPS -.PP -In Tisp there are no boolean types, much like common lisp, true is represented by the self evaluating symbol 't' and false is nil, represented as '()', an empty list. 'nil' and 'false' are also mapped to '()'. -.PP -Tisp also only has one builtin equality primitive, '=', which tests integers, symbols, strings, and objects which occupy the same space in memory, such as primitives. -.PP -Symbols are case sensitive, unlike many other older lisps, in order to better interface with modern languages. -.PP -Tisp is single value named, so procedures share the same namespace as variables, removing the need for common lisp's 'defunc' vs 'defvar', 'let' vs 'flet', and redundant syntax for getting the function from a symbol. -.PP .SH AUTHOR .PP Ed van Bruggen <ed@edryd.org> .PP .SH SEE ALSO .PP -See project page at <https://edryd.org/projects/tisp.html> +tisp(7) tsp(1) +.PP +See project at <https://edryd.org/projects/tisp> .PP View source code at <https://git.edryd.org/tisp> .PP diff --git a/doc/tisp.1.md b/doc/tisp.1.md @@ -1,20 +1,10 @@ # tisp \- tiny lisp -[![Build Status](https://travis-ci.org/edvb/tisp.svg)](https://travis-ci.org/edvb/tisp) - -Tisp is a tiny, terse, and transparent lisp library designed to be lightweight -and easy to embedded in other programs. Simply drop the `tisp.c` and `tisp.h` -files into your project in order to use the necessary functions for your -program. An example command line interpreter is provided in `main.c`. Tisp is a -single value name language (lisp-1) which tries to be unambiguous and focus -on simplicity. Much of the language is defined with Tisp itself leaving the C -code as short as possible. +Tisp programming language interpreter. Read and evaluate all files in order given, if file name +is `-` read from `stdin`. If no files are supplied launch REPL. ## Options -Read and evaluate all files in order given, if file name is `-` read from -`stdin`. If no files are supplied launch REPL. - #### -c COMMAND Read *COMMAND* as a line of Tisp code and print result @@ -34,7 +24,7 @@ to see the result. ``` $ tisp -(cons 1 2) +> (cons 1 2) (1 . 2) ``` @@ -61,211 +51,16 @@ $ tisp -c "(reverse '(1/2 1/4 1/8 1/16))" (1/16 1/8 1/4 1/2) ``` -## Language - -Tisp is mainly based off of scheme, with minor features borrowed from other -lisps and scripting languages. - -### General - -#### Comments - -Single line comments with a semicolon, **eg** `(cons 1 2) ; ingnored by tisp until new line`. - -### Types - -#### Nil - -Nil, null, empty, or false, represented as an empty list, **eg** `()`, `nil` `false`. - -#### Integers - -Whole real numbers, positive or negative with optional `+` or `-` prefixes -repressively. Also supports scientific notation with a capital or lowercase -`e`. The exponent needs to be an positive integer, it can also be negative but -that would just round to zero. **eg** `1`, `-48`, `+837e4`, `3E-2`. - -#### Decimals - -Floating point numbers, also know as decimals, are numbers followed by a period -and an optional mantissa. Like integers they can be positive or negative with -scientific notation, but still need an integer as an exponent. **eg** `1.`, -`+3.14`, `-43.00`, `800.001e-3`. - -#### Rationals - -Fraction type, a ratio of two integers. Similar rules apply for numerator and -dominator as integers (real positive or negative), except for scientific -notation. Will simplify fraction where possible, and will through error -on division by zero. **eg** `1/2`, `4/3` `-1/2`, `01/-30`, `-6/-3`. - -#### Strings - -String of characters contained inside two double quotes. Any character is -valid, including actual newlines, execpt for double quotes and backspace which -need to be escaped as `\"` and `\\` respectively. Newlines and tabs can also be -escaped with `\n` and `\t` **eg** `"foo"`, `"foo bar"`, `"string \"quoted\""`, -`"C:\\windows\\path"` `\twhite\n\tspace`. - -#### Symbols - -Case sensitive symbols which are evaluated as variable names. Supports lower and -upper case letters, numbers, as well as the characters `_+-*/\\^=<>!?@#$%&~`. -First character can not be a number, if the first character is a `+` or `-` -then the second digit cannot be a number either. Unlike all the previously -listed types, symbols are not self evaluating, but instead return the value -they are defined to. Throws an error if a symbol is evaluated without it being -previously assigned a value. **eg** `foo`, `foo-bar`, `cat9`, `+`, `>=`, -`nil?`. - -#### Lists - -Lists composed of one or more elements of any type, including lists themselves. -Expressed with surrounding parentheses and each element is separated by -whitespace. When evaluated the procedure found at the first element is run with -the rest of the elements as arguments. Technically list is not a type, but -simply a nil-terminated chain of nested pairs. A pair is a group of two and -only two elements, normally represented as `(a . b)`, with `a` being the first -element (car/first) and `b` being the second element (cdr/rest). For example -`(a b c)` is equivilent to `(a . (b . (c . ())))`, but it is often easier to -express them the first way syntactically. To create an improper list (not -nil-terminated list) the dot notation can be used, `(1 2 3 . 4)`. - -#### Functions - -Lambda functions created within Tisp itself. Called using list syntax where the -first element is the function name and any proceeding elements are the -arguments to be evaluated. For example `(cadr '(1 2 3))` is a list of elements -`cadr` and `'(1 2 3)`. It calls the function `cadr` which returns the 2nd -element of the argument given, in this case a list of size 3, which returns -`2`. **eg** `list`, `not`, `apply`, `map`, `root`, `sqrt`, `print` - -#### Primitives - -Procedures built in to the language written in C. Called like regular -functions, see primitives section for more details. **eg** `car`, `cond`, -`def`, `write`, `+` - -#### Macros - -Like lambda functions macros are defined within Tisp and are called in a -similar fashion. However unlike functions and primitives the arguments are not -evaluated before being given to the macro, and the output of a macro is -only evaluated at the end. This means instead of taking in values and returning -values, macros take in code and return code, allowing you to extend the -language at compile time. **eg** `if`, `and`, `or`, `let`, `assert` - -### Built-ins - -Built in primitives written in C included by default. - -#### car - -Returns first element of given list - -#### cdr - -Return rest of the given list, either just the second element if it is a pair, -or another list with the first element removed. - -#### cons - -Creates a new pair with the two given arguments, first one as the car, second -as the cdr. Can be chained together to create a list if ending with `nil`. - -#### quote - -Returns the given argument unevaluated. - -#### Void - -Returns nothing. Used to insert a void type in a list or force a function not -to return anything. - -#### eval - -Evaluates the expression given, can be dangerous to use in practice. In general -`apply` should be used instead. - -#### = - -Tests if multiple values are all equal. Returns `nil` if any are not, and `t` -otherwise. - -#### cond - -Evaluates each expression if the given condition corresponding to it is true. -Runs through all arguments, each is a list with the first element as the -condition which needs to be `t` after evaluated, and the rest of the list is -the body to be run if and only if the condition is met. Used for if/elseif/else -statements found in C-like languages and `if`,`when`,`unless`,`switch` macros -in Tisp. - -#### typeof - -Returns a string stating the given argument's type. Used to create `type?` -individual functions. - -#### lambda - -Creates function, first argument is a list of elements representing the symbol -name for any arguments of the new function. Rest of the arguments are code to -be run with the supplied arguments. - -#### macro - -Similar to lambda, creates anonymous macro with first argument as macro's -argument list and rest as macro's body. - -#### def - -Create variable with the name of the first argument, with the value of the -second. If name given is a list use the first element of this list as a new -functions name and rest of list as its arguments. If only variable name is -given make it self evaluating. - -#### set! - -Change the value of the of the variable given by the first argument to the -second argument. Errors if variable is not defined before. - -#### load - -Loads the library given as a string. - -#### error - -Throw error, print message given by second argument string with the first -argument being a symbol of the function throwing the error. - -#### version - -Return string of Tisp's version number. - -### Differences From Other Lisps - -In Tisp there are no boolean types, much like common lisp, true is represented -by the self evaluating symbol `t` and false is nil, represented as `()`, an -empty list. `nil` and `false` are also mapped to `()`. - -Tisp also only has one builtin equality primitive, `=`, which tests integers, -symbols, strings, and objects which occupy the same space in memory, such as -primitives. - -Symbols are case sensitive, unlike many other older lisps, in order to better -interface with modern languages. - -Tisp is single value named, so procedures share the same namespace as -variables, removing the need for common lisp's `defunc` vs `defvar`, `let` vs -`flet`, and redundant syntax for getting the function from a symbol. - ## Author Ed van Bruggen <ed@edryd.org> ## See Also -See project page at <https://edryd.org/projects/tisp.html> +tisp(7) +tsp(1) + +See project at <https://edryd.org/projects/tisp> View source code at <https://git.edryd.org/tisp> diff --git a/doc/tisp.7 b/doc/tisp.7 @@ -0,0 +1,161 @@ +.TH TISP 1 "March 2021" "tisp 0.0.0" +.PP +.SH NAME +tisp \- tiny lisp +.PP +.SH SYNOPSIS +tisp [-hv] [-c COMMAND] [-] [FILE ...] +.PP +.SH DESCRIPTION +.PP + +.PP +Tisp is a tiny, terse, and transparent lisp programming language designed to be lightweight and easy to embedded in other programs. Simply drop the 'tisp.c' and 'tisp.h' files into your project in order to use the necessary functions for your program. An example command line interpreter is provided in 'main.c'. Tisp is a single value name language (lisp-1) which tries to be unambiguous and focus on simplicity. Much of the language is defined with Tisp itself leaving the C code as short as possible. +.PP +The language is still in active development and not yet stable. Until the 'v1.0' release expect non-backwards compatible changes in minor releases. +.PP +.SH LANGUAGE +.PP +Tisp is mainly based off of scheme, with minor features borrowed from other lisps and scripting languages. +.PP +.SS GENERAL +.TP +\fBComments\fP +Single line comments with a semicolon, \fBeg\fP '(cons 1 2) ; ingnored by tisp until new line'. +.PP +.SS TYPES +.TP +\fBNil\fP +Nil, null, empty, or false, represented as an empty list, \fBeg\fP '()', 'nil' 'false'. +.PP +.TP +\fBIntegers\fP +Whole real numbers, positive or negative with optional '+' or '-' prefixes repressively. Also supports scientific notation with a capital or lowercase 'e'. The exponent needs to be an positive integer, it can also be negative but that would just round to zero. \fBeg\fP '1', '-48', '+837e4', '3E-2'. +.PP +.TP +\fBDecimals\fP +Floating point numbers, also know as decimals, are numbers followed by a period and an optional mantissa. Like integers they can be positive or negative with scientific notation, but still need an integer as an exponent. \fBeg\fP '1.', '+3.14', '-43.00', '800.001e-3'. +.PP +.TP +\fBRationals\fP +Fraction type, a ratio of two integers. Similar rules apply for numerator and dominator as integers (real positive or negative), except for scientific notation. Will simplify fraction where possible, and will through error on division by zero. \fBeg\fP '1/2', '4/3' '-1/2', '01/-30', '-6/-3'. +.PP +.TP +\fBStrings\fP +String of characters contained inside two double quotes. Any character is valid, including actual newlines, execpt for double quotes and backspace which need to be escaped as '\"' and '\\' respectively. Newlines and tabs can also be escaped with '\n' and '\t' \fBeg\fP '"foo"', '"foo bar"', '"string \"quoted\""', '"C:\\windows\\path"' '\twhite\n\tspace'. +.PP +.TP +\fBSymbols\fP +Case sensitive symbols which are evaluated as variable names. Supports lower and upper case letters, numbers, as well as the characters '_+-*/\\^=<>!?@#$%&~'. First character can not be a number, if the first character is a '+' or '-' then the second digit cannot be a number either. Unlike all the previously listed types, symbols are not self evaluating, but instead return the value they are defined to. Throws an error if a symbol is evaluated without it being previously assigned a value. \fBeg\fP 'foo', 'foo-bar', 'cat9', '+', '>=', 'nil?'. +.PP +.TP +\fBLists\fP +Lists composed of one or more elements of any type, including lists themselves. Expressed with surrounding parentheses and each element is separated by whitespace. When evaluated the procedure found at the first element is run with the rest of the elements as arguments. Technically list is not a type, but simply a nil-terminated chain of nested pairs. A pair is a group of two and only two elements, normally represented as '(a . b)', with 'a' being the first element (car/first) and 'b' being the second element (cdr/rest). For example '(a b c)' is equivilent to '(a . (b . (c . ())))', but it is often easier to express them the first way syntactically. To create an improper list (not nil-terminated list) the dot notation can be used, '(1 2 3 . 4)'. +.PP +.TP +\fBFunctions\fP +Lambda functions created within Tisp itself. Called using list syntax where the first element is the function name and any proceeding elements are the arguments to be evaluated. For example '(cadr '(1 2 3))' is a list of elements 'cadr' and ''(1 2 3)'. It calls the function 'cadr' which returns the 2nd element of the argument given, in this case a list of size 3, which returns '2'. \fBeg\fP 'list', 'not', 'apply', 'map', 'root', 'sqrt', 'print' +.PP +.TP +\fBPrimitives\fP +Procedures built in to the language written in C. Called like regular functions, see primitives section for more details. \fBeg\fP 'car', 'cond', 'def', 'write', '+' +.PP +.TP +\fBMacros\fP +Like lambda functions macros are defined within Tisp and are called in a similar fashion. However unlike functions and primitives the arguments are not evaluated before being given to the macro, and the output of a macro is only evaluated at the end. This means instead of taking in values and returning values, macros take in code and return code, allowing you to extend the language at compile time. \fBeg\fP 'if', 'and', 'or', 'let', 'assert' +.PP +.SS BUILT-INS +.PP +Built in primitives written in C included by default. +.PP +.TP +\fBcar\fP +Returns first element of given list +.PP +.TP +\fBcdr\fP +Return rest of the given list, either just the second element if it is a pair, or another list with the first element removed. +.PP +.TP +\fBcons\fP +Creates a new pair with the two given arguments, first one as the car, second as the cdr. Can be chained together to create a list if ending with 'nil'. +.PP +.TP +\fBquote\fP +Returns the given argument unevaluated. +.PP +.TP +\fBVoid\fP +Returns nothing. Used to insert a void type in a list or force a function not to return anything. +.PP +.TP +\fBeval\fP +Evaluates the expression given, can be dangerous to use in practice. In general 'apply' should be used instead. +.PP +.TP +\fB=\fP +Tests if multiple values are all equal. Returns 'nil' if any are not, and 't' otherwise. +.PP +.TP +\fBcond\fP +Evaluates each expression if the given condition corresponding to it is true. Runs through all arguments, each is a list with the first element as the condition which needs to be 't' after evaluated, and the rest of the list is the body to be run if and only if the condition is met. Used for if/elseif/else statements found in C-like languages and 'if','when','unless','switch' macros in Tisp. +.PP +.TP +\fBtypeof\fP +Returns a string stating the given argument's type. Used to create 'type?' individual functions. +.PP +.TP +\fBlambda\fP +Creates function, first argument is a list of elements representing the symbol name for any arguments of the new function. Rest of the arguments are code to be run with the supplied arguments. +.PP +.TP +\fBmacro\fP +Similar to lambda, creates anonymous macro with first argument as macro's argument list and rest as macro's body. +.PP +.TP +\fBdef\fP +Create variable with the name of the first argument, with the value of the second. If name given is a list use the first element of this list as a new functions name and rest of list as its arguments. If only variable name is given make it self evaluating. +.PP +.TP +\fBset!\fP +Change the value of the of the variable given by the first argument to the second argument. Errors if variable is not defined before. +.PP +.TP +\fBload\fP +Loads the library given as a string. +.PP +.TP +\fBerror\fP +Throw error, print message given by second argument string with the first argument being a symbol of the function throwing the error. +.PP +.TP +\fBversion\fP +Return string of Tisp's version number. +.PP +.SS DIFFERENCES FROM OTHER LISPS +.PP +In Tisp there are no boolean types, much like common lisp, true is represented by the self evaluating symbol 't' and false is nil, represented as '()', an empty list. 'nil' and 'false' are also mapped to '()'. +.PP +Tisp also only has one builtin equality primitive, '=', which tests integers, symbols, strings, and objects which occupy the same space in memory, such as primitives. +.PP +Symbols are case sensitive, unlike many other older lisps, in order to better interface with modern languages. +.PP +Tisp is single value named, so procedures share the same namespace as variables, removing the need for common lisp's 'defunc' vs 'defvar', 'let' vs 'flet', and redundant syntax for getting the function from a symbol. +.PP +.SH AUTHOR +.PP +Ed van Bruggen <ed@edryd.org> +.PP +.SH SEE ALSO +.PP +tisp(1) tsp(1) +.PP +See project at <https://edryd.org/projects/tisp> +.PP +View source code at <https://git.edryd.org/tisp> +.PP +.SH LICENSE +.PP +zlib License +.PP + diff --git a/doc/tisp.7.md b/doc/tisp.7.md @@ -0,0 +1,229 @@ +# tisp \- tiny lisp + +[![Build Status](https://travis-ci.org/edvb/tisp.svg)](https://travis-ci.org/edvb/tisp) + +Tisp is a tiny, terse, and transparent lisp programming language designed to be lightweight +and easy to embedded in other programs. Simply drop the `tisp.c` and `tisp.h` +files into your project in order to use the necessary functions for your +program. An example command line interpreter is provided in `main.c`. Tisp is a +single value name language (lisp-1) which tries to be unambiguous and focus +on simplicity. Much of the language is defined with Tisp itself leaving the C +code as short as possible. + +The language is still in active development and not yet stable. Until the `v1.0` release expect +non-backwards compatible changes in minor releases. + +## Language + +Tisp is mainly based off of scheme, with minor features borrowed from other +lisps and scripting languages. + +### General + +#### Comments + +Single line comments with a semicolon, **eg** `(cons 1 2) ; ingnored by tisp until new line`. + +### Types + +#### Nil + +Nil, null, empty, or false, represented as an empty list, **eg** `()`, `nil` `false`. + +#### Integers + +Whole real numbers, positive or negative with optional `+` or `-` prefixes +repressively. Also supports scientific notation with a capital or lowercase +`e`. The exponent needs to be an positive integer, it can also be negative but +that would just round to zero. **eg** `1`, `-48`, `+837e4`, `3E-2`. + +#### Decimals + +Floating point numbers, also know as decimals, are numbers followed by a period +and an optional mantissa. Like integers they can be positive or negative with +scientific notation, but still need an integer as an exponent. **eg** `1.`, +`+3.14`, `-43.00`, `800.001e-3`. + +#### Rationals + +Fraction type, a ratio of two integers. Similar rules apply for numerator and +dominator as integers (real positive or negative), except for scientific +notation. Will simplify fraction where possible, and will through error +on division by zero. **eg** `1/2`, `4/3` `-1/2`, `01/-30`, `-6/-3`. + +#### Strings + +String of characters contained inside two double quotes. Any character is +valid, including actual newlines, execpt for double quotes and backspace which +need to be escaped as `\"` and `\\` respectively. Newlines and tabs can also be +escaped with `\n` and `\t` **eg** `"foo"`, `"foo bar"`, `"string \"quoted\""`, +`"C:\\windows\\path"` `\twhite\n\tspace`. + +#### Symbols + +Case sensitive symbols which are evaluated as variable names. Supports lower and +upper case letters, numbers, as well as the characters `_+-*/\\^=<>!?@#$%&~`. +First character can not be a number, if the first character is a `+` or `-` +then the second digit cannot be a number either. Unlike all the previously +listed types, symbols are not self evaluating, but instead return the value +they are defined to. Throws an error if a symbol is evaluated without it being +previously assigned a value. **eg** `foo`, `foo-bar`, `cat9`, `+`, `>=`, +`nil?`. + +#### Lists + +Lists composed of one or more elements of any type, including lists themselves. +Expressed with surrounding parentheses and each element is separated by +whitespace. When evaluated the procedure found at the first element is run with +the rest of the elements as arguments. Technically list is not a type, but +simply a nil-terminated chain of nested pairs. A pair is a group of two and +only two elements, normally represented as `(a . b)`, with `a` being the first +element (car/first) and `b` being the second element (cdr/rest). For example +`(a b c)` is equivilent to `(a . (b . (c . ())))`, but it is often easier to +express them the first way syntactically. To create an improper list (not +nil-terminated list) the dot notation can be used, `(1 2 3 . 4)`. + +#### Functions + +Lambda functions created within Tisp itself. Called using list syntax where the +first element is the function name and any proceeding elements are the +arguments to be evaluated. For example `(cadr '(1 2 3))` is a list of elements +`cadr` and `'(1 2 3)`. It calls the function `cadr` which returns the 2nd +element of the argument given, in this case a list of size 3, which returns +`2`. **eg** `list`, `not`, `apply`, `map`, `root`, `sqrt`, `print` + +#### Primitives + +Procedures built in to the language written in C. Called like regular +functions, see primitives section for more details. **eg** `car`, `cond`, +`def`, `write`, `+` + +#### Macros + +Like lambda functions macros are defined within Tisp and are called in a +similar fashion. However unlike functions and primitives the arguments are not +evaluated before being given to the macro, and the output of a macro is +only evaluated at the end. This means instead of taking in values and returning +values, macros take in code and return code, allowing you to extend the +language at compile time. **eg** `if`, `and`, `or`, `let`, `assert` + +### Built-ins + +Built in primitives written in C included by default. + +#### car + +Returns first element of given list + +#### cdr + +Return rest of the given list, either just the second element if it is a pair, +or another list with the first element removed. + +#### cons + +Creates a new pair with the two given arguments, first one as the car, second +as the cdr. Can be chained together to create a list if ending with `nil`. + +#### quote + +Returns the given argument unevaluated. + +#### Void + +Returns nothing. Used to insert a void type in a list or force a function not +to return anything. + +#### eval + +Evaluates the expression given, can be dangerous to use in practice. In general +`apply` should be used instead. + +#### = + +Tests if multiple values are all equal. Returns `nil` if any are not, and `t` +otherwise. + +#### cond + +Evaluates each expression if the given condition corresponding to it is true. +Runs through all arguments, each is a list with the first element as the +condition which needs to be `t` after evaluated, and the rest of the list is +the body to be run if and only if the condition is met. Used for if/elseif/else +statements found in C-like languages and `if`,`when`,`unless`,`switch` macros +in Tisp. + +#### typeof + +Returns a string stating the given argument's type. Used to create `type?` +individual functions. + +#### lambda + +Creates function, first argument is a list of elements representing the symbol +name for any arguments of the new function. Rest of the arguments are code to +be run with the supplied arguments. + +#### macro + +Similar to lambda, creates anonymous macro with first argument as macro's +argument list and rest as macro's body. + +#### def + +Create variable with the name of the first argument, with the value of the +second. If name given is a list use the first element of this list as a new +functions name and rest of list as its arguments. If only variable name is +given make it self evaluating. + +#### set! + +Change the value of the of the variable given by the first argument to the +second argument. Errors if variable is not defined before. + +#### load + +Loads the library given as a string. + +#### error + +Throw error, print message given by second argument string with the first +argument being a symbol of the function throwing the error. + +#### version + +Return string of Tisp's version number. + +### Differences From Other Lisps + +In Tisp there are no boolean types, much like common lisp, true is represented +by the self evaluating symbol `t` and false is nil, represented as `()`, an +empty list. `nil` and `false` are also mapped to `()`. + +Tisp also only has one builtin equality primitive, `=`, which tests integers, +symbols, strings, and objects which occupy the same space in memory, such as +primitives. + +Symbols are case sensitive, unlike many other older lisps, in order to better +interface with modern languages. + +Tisp is single value named, so procedures share the same namespace as +variables, removing the need for common lisp's `defunc` vs `defvar`, `let` vs +`flet`, and redundant syntax for getting the function from a symbol. + +## Author + +Ed van Bruggen <ed@edryd.org> + +## See Also + +tisp(1) +tsp(1) + +See project at <https://edryd.org/projects/tisp> + +View source code at <https://git.edryd.org/tisp> + +## License + +zlib License