affine/SHS
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

more readme updates

Browse source
This commit is contained in:
Aidan 2021-05-23 21:45:26 -07:00
parent 8d2811be87
commit 7e3639d48b
No known key found for this signature in database
GPG key ID: 327711E983899316
1 changed files with 8 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

16
Readme.md
View file

@ -1,4 +1,4 @@
# shs # SHS
Syntactically Homogeneous Shell Syntactically Homogeneous Shell
## Overview ## Overview
@ -31,10 +31,10 @@ Elements in a list can be one of the following data types:
* **Symbol**: * **Symbol**:
- A symbol looks like a string without delimiters. - A symbol looks like a string without delimiters.
- A symbol denotes a variable or a function. - A symbol denotes a variable or a function.
* **List**: Any combination of multiple items seperated by a space. * **List**: Any combination of multiple items seperated by a space. (See above.)
### Function calls ### Function calls
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. Any list beginning in a symbol will be considered a function call. A user may typically expect to be able to start a list with a variable. However, given the current architecture this pattern must be maintained in order to enable shell functionality. Thus, from within the `shs` utility unknown symbols at the start of a list will be assumed to be system binaries.
Function call: `(append () 1 2 3)` Function call: `(append () 1 2 3)`
@ -81,7 +81,7 @@ Output: 9
### Control flow ### Control flow
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. 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 #### 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. The if form takes 3 arguments. It evaluates the first argument, the condition, and 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 (cond) (then) (else))
@ -118,12 +118,12 @@ Any characters after a semicolon will be ignored until end of line. Semicolons f
## How to build ## How to build
### Compiling/Installation ### Compiling/Installation
- 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. - For now simply run `go install ./cmd/shs` . If you have $GOPATH and $GOBIN set in your shell it should be usable with $PATH.
### Adding SHS to your application ### Adding SHS to your application
Here are some important tips for integrating an SHS REPL into another codebase. 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. * Make sure to set ast.SyncTablesWithOSEnviron and ast.ExecWhenFuncUndef, both 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 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. - If you do not want the user to be able to call binaries from the host system, set ast.ExecWhenFuncUndef to false.
- Create a new VarTable and FuncTable (see ast/var_table.go and ast/func_table.go). - Create a new VarTable and FuncTable (see ast/var_table.go and ast/func_table.go).
@ -132,7 +132,7 @@ Here are some important tips for integrating an SHS REPL into another codebase.
## Configuration ## Configuration
* Variables exported in the REPL, if of type string or number, will result in a corresponding environment variable. * 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 * One can write arbitrary SHS script into `.shsrc` including function and variable declarations
* Particularly useful are the following variables: * Particularly useful are the following variables:
- `SH_LOGGING` Sets the log level (from 0 to 3) - `SH_LOGGING` Sets the log level (from 0 to 3)
- `SHS_STATIC_PROMPT` Sets the prompt - `SHS_STATIC_PROMPT` Sets the prompt
@ -144,7 +144,7 @@ Here are some important tips for integrating an SHS REPL into another codebase.
- if the function does not return a string, its output will be discarded - if the function does not return a string, its output will be discarded
- afterwards, the repl will print the values in `SHS_STATIC_PROMPT` - afterwards, the repl will print the values in `SHS_STATIC_PROMPT`
Here is an example of a shs configuration file: Here is an example of a SHS configuration file:
```lisp ```lisp
(export GOPATH (concat HOME "/go")) (export GOPATH (concat HOME "/go"))
(export GOBIN (concat GOPATH "/bin")) (export GOBIN (concat GOPATH "/bin"))