Fork 0
Browse Source

Adds manpage and updates Makefile

sloum 1 year ago
  1. 16
  2. 2
  3. 65


@ -14,7 +14,21 @@ build:
${GOCMD} build -ldflags "-w -s" -o ${BINARY}
.PHONY: install
install: build
install: install-bin install-man clean
.PHONY: install-bin
install-bin: build
install -d ${DESTDIR}${BINDIR}
install -m 0755 ./${BINARY} ${DESTDIR}${BINDIR}
.PHONY: install-man
install-man: ${BINARY}.1
gzip -k ./${BINARY}.1
install -d ${DESTDIR}${MAN1DIR}
install -m 0644 ./${BINARY}.1.gz ${DESTDIR}${MAN1DIR}
.PHONY: clean
${GOCMD} clean
rm -f ./${BINARY}.1.gz 2> /dev/null
rm -f ./${BINARY}_* 2> /dev/null


@ -75,7 +75,7 @@ slosh only supports very basic output redirection. There is no separation of std
## Command Continuation
### Command Continuation
You can run multiple commands from the same line of input via the `&&` command. If any command in the line fails, the following ones will not run. The `&&` opperator is particularly useful for allow the `let` command (see below) to function and provide commands with local environment variables.


@ -0,0 +1,65 @@
.TH "slosh" 1 "09 JUL 2021" "" "General Operation Manual"
\fBslosh\fP- sloum's shell, a simple command shell
.fam C
.fam T
\fBslosh\fP a simple shell intended for use as a login shell, but which can be run as an interactive shell. Its main design goal is simplicity. It does away with all programming constructs, while keeping pipelines and commang continuation via the \fI|\fP and \fI&&\fP commands. The general idea being that you can always run a programming language or an interpretive shell with scripting capabilities on top of \fBslosh\fP.
.SS General Grammar
slosh works like most shells: commands are issued as a series of whitespace separated words/symbols. When the enter key is pressed the command sequence is parsed and acted upon.
.SS Paths
Contrary to many shells, changing paths can occur just by typing an absolute or relative path. All paths must begin with \fI..\fP, \fI./\fP, \fI~\fP, or \fI/\fP for slosh to recognize them for this purpose. The \fIcd\fP and \fIdir\fP command words are also available for compatibility reasons and they are aliased to the comandless behavior (the \fIcd\fP is dropped and it is treated as a bare path).
Filepath globbing via \fI*\fP and \fI**\fP, as wildcards, within a path will be expanded to all valid paths that can be represented by the wildcards. Each of these paths will be treated as a separate argument.
.SS Strings
Using quotes around a group of words will tell the shell to treat them as a single argument being passed to the given program. A string created with double quotes will have any variables within it expanded. A string created with single quotes will not have variables expanded and will be treated literally.
.SS Pipelines
Piping works similarly to other shells, except that both stdout and stderr get piped. Pipes between commands are created via the \fI|\fP character.
.SS Redirection
slosh supports very basic output redirection via the \fI>\fP (to write to a file, clobbering any existing data) and \fI>>\fP (appending to a given file, creating it if it doesn't exist) commands. These commands must be followed by a path or an error will result. Redirection always redirects both stdout and stderr.
.SS Command Continuation
Running multiple subsequent commands is achieved via the \fI&&\fP command. If any command in a series of commands joined by \fI&&\fP exits with a non-zero exit code, execution of further commands will stop. The \fI&&\fP is also very useful for setting local execution environment variables (see: local variables).
.SS Variables
slosh has two types of variables. A \fIglobal\fP variable is created via the \fIset\fP keyword. The first argument to \fIset\fP is the name of the variable that is being set, and any subsequent arguments are concatenated into a space separated string (unless they are already a string, which is passed as is). Global variables can be accessed at the command line by prefixing their name with a \fI$\fP. Thus, \fI$SHELL\fP would get expande, but \fISHELL\fP would not. Expansion happens when the command is issued from the shell and will not occur within single quoted strings. Any variable that does not exist, but is referenced, will be treated as an empty string for expansion purposes. A global variable can be removed from the system via the \fIunset\fP command, which takes a single argument: the name of the variable to unset.
A local variable is created via the \fIlet\fP keyword. The first argument to \fIlet\fP is the name of the variable, any subsequent arguments are treated as the value and concatenated together as a space separated string (unless they are already a string, which is passed as is). Local variables cannot be accessed via the command line and are only in the environment of any other commands being run from the same command line entry (joined via the \fI&&\fP command). They cease to exist when all commands from the command line entry are finished executing (or execution has halted due to error).
.SS Aliasing
The \fIalias\fP command takes as its first argument the new command name that you are creating. All subsequent values are treated as the command that will be run when the new alias name is called. Aliases are not recursive (they will not expand values from other aliases when run).
The shell will attempt to access the file \fI~/.slosh\fP when it starts up. Any commands inside of it will be run. This is a good place to set aliases, global variables, run any initialization commands, etc. Commands are run as if they were typed in line by line at the shell and are not treated differently for being in this file. One exception exists: any line beginning with \fI#\fP is treated as a comment and is ignored when processing the slosh file.
The \fB$SLOSH_PROMPT\fP variable can be set to create a prompt that differs from the initial one provided by the shell. It does not allow escape characters/codes/ansi-sequences/etc; these will have any non-printing characters removed and the remaining characters will be printed verbatim. There are some recognized replacement patterns that can be used to create a slightly more dynamic prompt:
The current base directory
A short version, up to three path segments, of the current path
The current full path
The current host
The current user
slosh is not a programming language the way bash and many other shell/command languages are. There are no if statements, no loops, etc. The general ethos behind slosh has been: if you want to program you can either write a bash script and execute it with bash or you can use a programming language. slosh is meant to be a very minimal shell that provides a basic feature set to allow you to navigate a system successfully, but not much more.
There is no support for job control (moving processes to the background, foreground, etc). A terminal multiplexer (tmux, dvtm, mtm, screen) can easily solve the problem of working on multiple things from a single terminal window and as such there is no need, in post cases, for the shell to handle this.
There are very likely bugs. This software was largely made for personal use and is being made available so that others can modify it to their needs if they would like. Feel free to fork and patch as you see fit (within the terms of the license).
(c) 2021 by sloum <sloum AT rawtext.club>, all rights reserved
\fBslosh\fP is available under the terms of the Floodgap Free Software License: \fIhttps://www.floodgap.com/software/ffsl/license.html\fP