.Dd $Mdocdate: April 11 2024 $
.Dt DWVSH 1
.Os
.Sh NAME
.Nm dwvsh
.Nd A (mostly) POSIX compliant shell
.Sh SYNOPSIS
.Nm
.Op Ar file ...
.Nm
.Op Fl l
.Sh DESCRIPTION
.Nm
is a (mostly) POSIX compliant shell, and tiny functional programming language
for U**x-like operating systems.
.Nm
is designed to be fully compatible with
.Xr bash 1 .
See BUGS for more info on this.
.Ss Builtin commands
Currently,
.Nm
supports the following builtin commands:
.Bl -tag -width "unalias" -compact
.It Pa alias
Allow users to define their own command aliases (i.e. alias vim=nvim).
.It Pa cd
Change directory.
.It Pa exit
Exit the shell.
.It Pa export
Set an environment variable, or list all environment variables.
.It Pa source
Run another shell script, retaining it's environment in the current shell.
.It Pa unalias
Clear a user defined command alias.
.It Pa unset
Clear an environment variable.
.El
.Ss Builtin command aliases
.Bl -tag -width "unalias" -compact
.It Pa quit
Aliased to exit.
.It Pa set
Aliased to export.
.El
.Sh OPTIONS
.Bl -tag -width 5n
.It Fl l
The shell is a login shell (only applicable if
.Fl l
is the only flag specified).
.El
.Sh FILES
.Bl -tag -width "/etc/dwvshrc" -compact
.It Pa /etc/dwvshrc
Global RC file for
.Nm ,
always sourced when launched.
.It Pa ~/.dwvshrc
User defined RC file for
.Nm ,
may or may not exist.
.El
.Sh SEE ALSO
.Xr bash 1 ,
.Xr sh 1 ,
.Sh EXAMPLES
.Nm
May be invoked with or without arguments. If ran with arguments, it will
attempt to read and run the file(s) specified. If ran without arguments it will
start up an interactive REPL.
.Ss With arguments
Imagine a file, hello.sh:
.Bd -literal -offset indent
#!/usr/bin/env sh
echo 'Hello from dwvsh!'
.Ed
.Pp
You can run this file with
.Nm
as shown below:
.Bd -literal -offset indent
$ dwvsh hello.sh
Hello from dwvsh!
.Ed
.Pp
Alternatively, you could change the first line of the script to:
.Bd -literal -offset indent
#!/usr/bin/env dwvsh
.Ed
.Pp
Then simply call the script directly:
.Bd -literal -offset indent
$ chmod +x hello.sh
$ ./hello.sh
Hello from dwvsh!
.Ed
.Ss Without arguments
This will start the read-eval-print-loop (REPL).
The default/fallback prompt for
.Nm
is '|> ', but this may be changed by setting the PS1 environment variable, for
instance:
.Bd -literal -offset indent
|> export PS1='$ '
$ 
.Ed
.Sh BUGS
.Nm
is still in alpha, so it is missing a lot of functionality compared to
.Xr bash 1 .
.Pp
In particular:
.Pp
- No way to redirect STDERR.
.br
- No builtin history.
.br
- Missing builtin commands (i.e. bind, etc).
.br
- No control flow.
.br
- No wildcards in paths.
.br
- No brace expansion in paths.
.br
- No tab autocompletion.
.br
- Man page and other documentation are woefully incomplete.
.Sh AUTHORS
.An Rory Dudley