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. It can be used for both system administration (as one might use bash or zsh) as well as for the creation of simple programs.

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, 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)

Comments

The standard delimiter for comments is ; any characters after a semicolon will be ignored until end of line

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

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

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
  • 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
  • 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:

(export GOPATH (concat HOME     "/go"))
(export GOBIN  (concat GOPATH  "/bin"))
(export PATH   (concat PATH ":" GOBIN))
(export GIT_TERMINAL_PROMPT 1)
(export SH_HIST_FILE (concat HOME "/.shs_hist"))
(export SH_LOGGING 0)
(export SHS_STATIC_PROMPT ">")
(func _SH_PROMPT () (concat (?) ($ basename ($ pwd)) "\n"))

The Docs

• Documentation on language interpreter
• Documentation on logging module
• Documentation on configuration module
• Documentation on utility functions
• Documentation on standard library
• Guide to standard library

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.

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