updated readme to improve documentation
This commit is contained in:
Aidan
parent
c2b86b7f4d
commit
87b11cff7a
1 changed files with 103 additions and 41 deletions
144
Readme.md
144
Readme.md
|
|
@ -2,86 +2,147 @@
|
|||
Syntactically Homogeneous Shell
|
||||
|
||||
## Overview
|
||||
This shell was created to have extremely simple syntax. S-Expressions were chosen to represent statements and the scope of language features were constrained to what could be considered practical for daily shell use. This program is meant to be practical for administrators and daily power users. It can be used for both system administration (as one might use bash or zsh) as well as for the creation of simple programs.
|
||||
This shell was created to have extremely simple syntax. S-Expressions were chosen to represent statements and the scope of the language features were constrained to what could be considered practical for daily shell use. This program is meant to be practical for administrators and daily power users. It can be used for both system administration (as one might use bash or zsh) as well as for the creation of simple programs as one might use Python, Racket, or Visual Basic.
|
||||
|
||||
## Basic Syntax
|
||||
When in doubt the `print_ast` utility can be used to examine the output of the Lex+Parse process. Here you can spot any bugs regarding syntax.
|
||||
When in doubt the `print_ast` utility can be used to examine the output of the Lexing and Parsing process. Here you can spot any bugs regarding syntax.
|
||||
`$ print_ast (example invocation`
|
||||
|
||||
### Lists
|
||||
Any sequence of items within a set of parenthesis is a list
|
||||
`(1 "two" three 4)`
|
||||
Any sequence of items within a set of parenthesis is a list.
|
||||
|
||||
Lists can be infinitely nested
|
||||
`("one" (2 3 4 (5)))`
|
||||
For Example: `(1 "two" three 4)`
|
||||
|
||||
Lists can be infinitely nested: `("one" (2 3 4 (5)))`
|
||||
|
||||
### Data types
|
||||
We use the following data types
|
||||
* Number: 1, 2.0, etc
|
||||
* String: "this is a string" (string delimiters: ' " \`)
|
||||
* Bool: T or F
|
||||
* Symbol: a string with no delimiters
|
||||
* List: a sequence of elements within parenthesis
|
||||
Elements in a list can be one of the following data types:
|
||||
* **Number**: A number can be written in one of the following formats:
|
||||
- integers: 1, 2, 3, etc...
|
||||
- rational numbers: 1.22, 2.24, etc...
|
||||
* **String**: Strings must use one of the following delimiters:
|
||||
- "this string is a proper string"
|
||||
- 'this is also a proper string'
|
||||
- \` this is another proper string\`
|
||||
* **Boolean**: Boolean values can take the following forms:
|
||||
- true: "T"
|
||||
- false: "F"
|
||||
* **Symbol**:
|
||||
- A symbol looks like a string without delimiters.
|
||||
- A symbol denotes a variable or a function.
|
||||
* **List**: Any combination of multiple items seperated by a space.
|
||||
|
||||
### Function calls
|
||||
Any list beginning in a symbol will be considered a function call.
|
||||
From within the `shs_repl` utility, unknown symbols will be assumed to be system binaries.
|
||||
Any list beginning in a symbol will be considered a function call. This departs from traditional lisps, and a user may typically expect to be able to start a list with a variable. Given the current architecture this pattern must be maintained in order to enable shell functionality. Thus, from within the `shs_repl` utility unknown symbols will be assumed to be system binaries.
|
||||
|
||||
`(append () 1 2 3)`
|
||||
`(vim Readme.md)`
|
||||
`(if (eq "example" (fread 'test_file')) (print "test worked) (rm -rf /))`
|
||||
Function call: `(append () 1 2 3)`
|
||||
|
||||
System binary call: `(vim Readme.md)`
|
||||
|
||||
Control flow statement (enabled by function call): `(if (eq "example" (fread 'test_file')) (print "test worked) (rm -rf /))`
|
||||
|
||||
There may be alternative REPLs, officially or from community members, that do not exhibit this behavior.
|
||||
|
||||
### Variable declaration
|
||||
There are a few ways to export variables
|
||||
* export: `(export NAME (value))`
|
||||
* let: `(let ((var1 val1) (var2 val2)) (form_to_be_evaluated))`
|
||||
Export is used to define variables.
|
||||
|
||||
Currently, let has yet to be implemented
|
||||
`(export NAME (value))`
|
||||
|
||||
Users may also leverage the `export` function to create aliases in the SHS shell.
|
||||
|
||||
```
|
||||
(export vim nvim)
|
||||
(vim /path/to/file.c)
|
||||
```
|
||||
|
||||
The above example will call exec with the arguments "nvim" and "/path/to/file.c".
|
||||
|
||||
### Function declaration
|
||||
Use the `func` function from the stdlib:
|
||||
`(func name (var1, var2, var3) (form_to_be_evaluated))`
|
||||
In this case, `(form_to_be_evaluated)` will not be evaluated until the function is called.
|
||||
|
||||
Example call: `(func name (var1, var2, var3) (form_to_be_evaluated))`
|
||||
|
||||
In the above example, a function is defined with the following attributes:
|
||||
- The function is named "name".
|
||||
- The function takes three arguments: arg1, arg2, and arg3.
|
||||
- When the function is called, "(form_to_be_evaluated)" is evaluated.
|
||||
|
||||
SHS will only lex (form_to_be_evaluated). It will not parse or execute it until the function is invoked.
|
||||
|
||||
In the below example a function named addthree is defined. The function takes three arguments, and returns the sum of them.
|
||||
|
||||
```
|
||||
(func addthree (a b c) (+ a b c))
|
||||
(addthree 2 3 4)
|
||||
Output: 9
|
||||
```
|
||||
|
||||
### Control flow
|
||||
See `stdlib/control_flow.go`. We have if, while, and progn forms:
|
||||
`(if (cond) (then) (else))`
|
||||
`(when (cond) (form1)....... (formN))`
|
||||
`(progn (form1)..... (formN))`
|
||||
If and While should be self explanatory. For those new to LISP, the rough idea of progn is to evaluate a sequence of N forms and return the result of the final one.
|
||||
We also have functioning implementations of map and reduce in the stdlib (incomplete)
|
||||
SHS currently uses the following control flow forms for daily use. Although, it is not hard to create your own in the SHS source code.
|
||||
#### if statements
|
||||
The if form takes 3 arguments. It evaluates the first (the condition) if it evaluates to true (T) it evaluates the second argument. If the first argument evaluates to false (F) the `if` routine then evaluates the third argument. The argument that is not used will not be parsed or evaluated. The whole statement will, however, be lexed.
|
||||
|
||||
```
|
||||
(if (cond) (then) (else))
|
||||
(if (= 1 1.0) (print "numbers are equal") (print "numbers are not equal"))
|
||||
```
|
||||
|
||||
#### while loops
|
||||
The while loop takes N arguments. The first argument, the conditional, must evaluate to a boolean value (T or F). If the first argument is evaluated to T, all subsequent arguments are evaluated. If the first argument evaluates to F, while returns. Finally, the conditional is re-evaluated and the loop begins again.
|
||||
|
||||
```
|
||||
(while (cond) (form1)....... (formN))
|
||||
|
||||
(export iter 1)
|
||||
(while (< iter 4)
|
||||
(print (concat "current iteration: "
|
||||
(string iter)))
|
||||
(export iter
|
||||
(+ iter 1)))
|
||||
|
||||
Output:
|
||||
current iteration: 1
|
||||
current iteration: 2
|
||||
current iteration: 3
|
||||
```
|
||||
|
||||
## Comments
|
||||
The standard delimiter for comments is ;
|
||||
any characters after a semicolon will be ignored until end of line
|
||||
Any characters after a semicolon will be ignored until end of line. Semicolons found in strings will not be considered comment delimiters.
|
||||
|
||||
```
|
||||
; this comment explains the value in myvar
|
||||
(export myvar "testvar")
|
||||
```
|
||||
|
||||
## How to build
|
||||
### Compiling/Installation
|
||||
- For now simply run `go install cmd/...` for each utility you wish to use. If you have GOPATH and GOBIN set it should be usable from PATH
|
||||
- For now simply run `go install ./cmd/shs` for each utility you wish to use. If you have $GOPATH and $GOBIN set in your shell it should be usable with $PATH.
|
||||
|
||||
### Adding SHS to your application
|
||||
Here are some important tips for integrating an SHS REPL into another codebase.
|
||||
|
||||
* Make sure to set ast.SyncTablesWithOSEnviron, ast.ExecWhenFuncUndef. All of which control integrations with the underlying system.
|
||||
- If you do not want the user to be able to set environment variables set ast.SyncTablesWithOSEnviron to false.
|
||||
- If you do not want the user to be able to call binaries from the host system, set ast.ExecWhenFuncUndef to false.
|
||||
- Get text you are interested in parsing
|
||||
- Create a new VarTable and FuncTable (see ast/var_table.go and ast/func_table.go)
|
||||
- Call `Lex(text)` on the `text` you want to evaluate to recieve a tree of parsed lexemes.
|
||||
- Call `tree.Eval(FuncTable, VarTable, false)` where tree is the returned data from Lex, and the final boolean argument is whether or not to convert unknown symbols to strings. (this is a helpful option if you are writing functions such as those in stdlib/call.go, or any funciton in which you may want to be able to edit and transform the final ast based on your own varaiable table)
|
||||
- Make sure the GPLv3 is adhered to
|
||||
- *OVERRIDE THE STDLIB GenFuncTable FUNCTION.* You very likely do NOT want an available function to call system binaries in your embedded shell. Make sure the stdlib Call function is not included.
|
||||
- Create a new VarTable and FuncTable (see ast/var_table.go and ast/func_table.go).
|
||||
- Make sure to adhere to the terms and conditions stated in the GPLv3.
|
||||
- *OVERRIDE THE STDLIB GenFuncTable FUNCTION.* You very likely do NOT want an available function to call system binaries in your embedded shell. Make sure the stdlib Call function is not included in your GenFuncTable inplementation.
|
||||
|
||||
## Configuration
|
||||
* variables exported in the repl, if of types string or number, will result in a corresponding variable added to the Environment.
|
||||
* one can write arbitrary shs script into `.shsrc` including function and variable declarations
|
||||
* of note are the following variables
|
||||
* Variables exported in the REPL, if of type string or number, will result in a corresponding environment variable.
|
||||
* One can write arbitrary shs script into `.shsrc` including function and variable declarations
|
||||
* Particularly useful are the following variables:
|
||||
- `SH_LOGGING` Sets the log level (from 0 to 3)
|
||||
- `SHS_STATIC_PROMPT` Sets the prompt
|
||||
- `SH_HIST_FILE` Sets the history file
|
||||
- `SH_DEBUG_MODE` Adds additional debug output for the lexer (high clutter)
|
||||
* additionally, the repl will evaluate any function you define as `_SH_PROMPT` before the shell prompt
|
||||
* Additionally, the REPL will evaluate any function you define as `_SH_PROMPT` before the shell prompt.
|
||||
- if defined, the function will be evaluated before printing the prompt
|
||||
- the function will be given 0 arguments
|
||||
- if the function does not return a string, its output will be discarded
|
||||
- afterwards, the repl will print the values in `SHS_STATIC_PROMPT`
|
||||
|
||||
Here is an example of a shs configuration file:
|
||||
```lisp
|
||||
(export GOPATH (concat HOME "/go"))
|
||||
|
|
@ -95,6 +156,7 @@ Here is an example of a shs configuration file:
|
|||
```
|
||||
|
||||
## The Docs
|
||||
What follows are links to documentation for the code and interfaces used by SHS. This documentation is automatically generated by godoc, and in times of transition may not be complete.
|
||||
- [Documentation on language interpreter](https://godoc.org/gitlab.com/whom/shs/ast)
|
||||
- [Documentation on logging module](https://godoc.org/gitlab.com/whom/shs/log)
|
||||
- [Documentation on configuration module](https://godoc.org/gitlab.com/whom/shs/config)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue