From: Jon Feldman Date: Wed, 26 Jul 2017 18:24:05 +0000 (-0400) Subject: docs: fix up for initial push X-Git-Url: https://chaos.moe/g/?a=commitdiff_plain;h=3b96f1cdd0eb15635d83c67243f43203e0edd6e0;p=misc%2Fysh.git docs: fix up for initial push --- diff --git a/DOC/DEFICIENCES.md b/DOC/DEFICIENCES.md deleted file mode 100644 index e69de29..0000000 diff --git a/DOC/EXAMPLES.md b/DOC/EXAMPLES.md deleted file mode 100644 index e69de29..0000000 diff --git a/DOC/PATH_RESOLUTION.md b/DOC/PATH_RESOLUTION.md deleted file mode 100644 index e69de29..0000000 diff --git a/DOC/PITFALLS.md b/DOC/PITFALLS.md index f619edf..0692af6 100644 --- a/DOC/PITFALLS.md +++ b/DOC/PITFALLS.md @@ -8,6 +8,9 @@ This is not POSIX compliant. It is not intended to be, since this contorts the shell into working in a certain manner, and in practice, /bin/sh usually means /bin/bash. +Long story short, use your /bin/sh interpreter for POSIX compliance. +This isn't intended to fill that role. + Subcommands ------------ @@ -24,21 +27,39 @@ echo $ echo hello $ ho echo world -xsh: echo {echo hello {echo world} ho} +> hello world ho + +ysh: echo {echo hello {echo world} ho} echo {echo hello $ ho} echo world echo $ echo hello world ho -This behavior has a few importan6 things to note about it. +> hello world ho + +This behavior has a few important things to note about it. + 1) Subcommands inherit the environment of the shell, not a "parent" subcommand. - 2) Subcommands do not spawn another shell. + + 2) Subcommands do not spawn another shell, or if they are + builtin, they do not even spawn another process. + + 3) Due to points 1 and 2 above, subcommand environment must be + carefully handled since unless you have created a subcommand + like {ysh -c "command"} it will NOT explicitly spawn another + process. + + 4) Output from subcommands are stripped of the last trailing '\n' + to prevent odd formatting. Variables ---------- +* NOTE: Subject to change, since this feature is not fully implemented + yet. + Variables (starting with the $ character) are resolved after subcommands and double-quoted strings. Consider the following: @@ -46,6 +67,7 @@ Consider the following: = NAME 42 echo "${echo NAME}" -So first, echo NAME is evaluated. The contents of the double-quoted string -are then evaluated, leaving a string named "$NAME". This is then interpreted to -be a variable, resulting in the output 42. +So first, echo NAME is evaluated. The contents of the double-quoted +string are then evaluated, leaving a string named "$NAME". This is then +scanned for variables, resulting in the replacement of $NAME -> 42, and +thus the output is 42. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c7554fd --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +ysh +----- + +Yeah, it's a shell. + +While this is a toy project that's been going on for less than a week, I plan to continue it due to the interesting technical challenges[1] a shell provides in implementation. + +Goals of this shell include: + + * Keeping code simple when possible[2] + + * When the above is impossible, documenting well what the heck is going on + + * Allowing to express input in the most compact way possible[3] + + * Being light on memory and not requiring odd libc "features"[4] + +The last goal (compactness) is at odds with POSIX-sh-compliance, so this shell makes no attempt to be usable as /bin/sh. + +----------- + +[1] Subprocess spawning (such as bash's "$(...)" and "`...`" constructs) is one hell of a thing. You'd be surprised at how much something simple like evaluation of strings increases complexity of a parser; or rather, it forces parsing and execution into the same phase. + +[2] Litmus test for simple: if you look at the relevant code a week later, do you know what it's doing? If the answer isn't a resounding "YES", it needs comments and potentially documentation. If the code looks like garbage, it needs a refactor. Simple doesn't mean stupid. It means not adding uneeded complexity. + +[3] Yes, this is contrary to the goals within the source code of the shell. Shell scripts and commands may end up looking like a clusterfuck, but shorter than POSIX sh equivalents. This is intentional. + +[4] Namely, avoidance of glibc-isms. GNU extensions are barred from usage. This shell is tested against musl and glibc but hopefully random embedded libc X will work as well. diff --git a/builtin/exec.c b/builtin/exec.c index e69de29..437f6bb 100644 --- a/builtin/exec.c +++ b/builtin/exec.c @@ -0,0 +1 @@ +// Future home of the exec builtin diff --git a/builtin/math.c b/builtin/math.c index e69de29..f7eb024 100644 --- a/builtin/math.c +++ b/builtin/math.c @@ -0,0 +1 @@ +// Future home of 'math' builtins. diff --git a/builtin/spawn.c b/builtin/spawn.c index e69de29..60e2de9 100644 --- a/builtin/spawn.c +++ b/builtin/spawn.c @@ -0,0 +1 @@ +// Future home of the background process handling builtins.