SHS/Readme.md

# shs
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.

## 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.

### Lists
Any sequence of items within a set of parenthesis is a list
`(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

### 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.

`(append () 1 2 3)`
`(vim Readme.md)`
`(if (eq "example" (fread 'test_file')) (print "test worked) (rm -rf /))`

### Variable declaration
There are a few ways to export variables
* export: `(export NAME (value))`
* let: `(let ((var1 val1) (var2 val2)) (form_to_be_evaluated))`

Currently, let has yet to be implemented

### 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.

### Control flow
See `stdlib/control_flow.go`. We have if and while forms:
`(if (cond) (then) (else))`
`(when (cond) (form1)....... (formN))`

We also have functioning implementations of map and reduce in the stdlib

## 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

### Adding SHS to your application
- TODO: write a how to here
- 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.

## Configuration
* one can write arbitrary shs script into `.shsrc` including function and variable declarations
* of note are the following variables
    - `SH_LOGGING` Sets the log level (from 0 to 3)
    - `SHS_SH_PROMPT` Sets the prompt
    - `SH_HIST_FILE` Sets the history file
    - `SH_DEBUG_MODE` Adds additional debug output for the lexer

## Contributing
- Any contribution to this software is welcome as long as it adheres to the conduct guidelines specified in the `Contributing.md` file in this repository.
- Consider reading the [STDLIB Readme](https://git.callpipe.com/aidan/shs/-/blob/master/stdlib/Readme.md) for more information on how to extend this project.

## License
Copyright (C) 2019 Aidan Hahn.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.