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