Commit 2f720c88 authored by Samuel Newbold's avatar Samuel Newbold

Horrendously out of date documentation in misformated markdown

parent 88f1bd7c
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>argument functions</title>
</head>
<body>
Along with normal text arguments, commands can include argument
functions enclosed in braces. For example,<br>
.function sel {echo $SELECT}<br>
The function builtin is passed "sel" as $1 and "echo $SELECT" as an
argument function. The function builtin creates a new function in the
executable map using $1 for the name and the argument function for the
content. Braces are recognized as special characters. Currently, the
close brace does not need
any whitespace around it, though the open brace must be preceeded by
whitespace to distinguish it from a substitution. It is likely that the
close brace will require whitespace following it to make it
easier/possible to include the character in normal arguments. The
argument function may also occur anywhere in the command
line, not just at the end (e.g. ".function {echo $SELECT}sel" is
equivalent to the command given above.) Empty braces ("{}") refer to
the same empty command that a blank line does.<br>
<br>
There are also four constructs named like internal functions to permit
user-defined functions to use argument functions themselves:
rwsh.mapped_argfunction, rwsh.unescaped_argfunction, rwsh.argfunction
and rwsh.escaped_argfunction. Each of these is used as an executable
name to get the special meaning. Since they are not keywords, they can
be used as arguments to commands without the shell interfering. Of them
only rwsh.mapped_argfunction can take arguments itself.<br>
<br>
<h3>rwsh.mapped_argfunction</h3>
rwsh.mapped_argfunction executes its argument function with the given
arguments. For example<br>
<pre>rwsh.mapped_argfunction z c {echo x y $1; echo a b $2; echo $0}</pre>
will output<br>
<pre>x y z<br>a b c<br>rwsh.mapped_argfunction</pre>
Nested argument functions are possible, and variables are not
interpretted for argument functions until they are run. For example<br>
<pre>rwsh.mapped_argfunction 1 2 3 {echo $*; rwsh.mapped_argfunction a b $1<br>{echo $*; rwsh.mapped_argfunction x $2 $3 {echo $*}}}</pre>
will output<br>
<pre>1 2 3<br>a b 1<br>x b 1</pre>
<h3>rwsh.unescaped_argfunction and rwsh.argfunction</h3>
Suppose that you wanted a function to provide a shorter name for
.function. What you need is a way of passing the argument function for
the current function an an argument function to the command that it
calls. Each time an argument script is interpretted
rwsh.unescaped_argfunction is replaced by the current argument function
and rwsh.argfunction is replaced by rwsh.unescaped_argfunction.<br>
<br>
so if you type<br>
<pre>.function fn {.function $* {rwsh.argfunction}}</pre>
the result of interpretting the command line results in<br>
<pre>.function fn {.function $* {rwsh.unescaped_argfunction}}</pre>
which places ".function $* {rwsh.unescaped_argfunction}" in the
executable_map with name fn.<br>
<br>
if you then type <br>
<pre>fn sel {echo $SELECT}</pre>
the command is unchanged by interpretation, and the function that is
stored under fn gets interpretted to be<br>
<pre>.function sel {echo $SELECT}</pre>
If we had instead typed<br>
<pre>.function fn {.function $* {rwsh.unescaped_argfunction}}</pre>
It would have been interpretted to result in<br>
<pre>.function fn {.function $* {.function $* {rwsh.unescaped_argfunction}}}</pre>
The result would have been a function that takes an argument function
and defines a second function which, when run, would define a function
to execute the argument function that was passed to the first function.<br>
<br>
The which command seeks to describe what is in the executable map in
the terms that you would use to put it there rather than what is
actually there. Thus<br>
<pre>which fn</pre>
prints out<br>
<pre>.function fn {.function $* {rwsh.argfunction}}</pre>
instead of what is stored, which is<br>
<pre>.function $* {rwsh.unescaped_argfunction}</pre>
The which command also recognizes the names rwsh.mapped_argfunction and
rwsh.argfunction to request the printing of the specified argument
function. In these cases the ".function rwsh.argfunction " part of the
print out is omitted for various reasons. For example, we could define
fn_v<br>
<pre>fn fn_v {.echo adding \ ; which rwsh.argfunction {rwsh.argfunction};<br>.echo \ to executable map as $1; fn $* {rwsh.argfunction}}</pre>
then running<br>
<pre>fn_v sel {echo $SELECT}</pre>
would print out<br>
<pre>adding {echo $SELECT} to executable map as sel</pre>
<h3>rwsh.escaped_argfunction</h3>
Suppose you wanted to define a function fn-fn such that it defined a
function with the name of its first argument which was equivalent to
.function. It needs to incorporate the
argument function, but not its own argument function, the new
function's argument
function. The solution is rwsh.escaped_argfunction, which is replaced
by rwsh.argfunction when interpretted. fn-fn can be defined as follows:<br>
<pre>.function fn-fn {.function $1 {.function $* {rwsh.escaped_argfunction}}}</pre>
<h3>argfunction call as the result of an interpretation</h3>
If you gave the command<br>
<pre>rwsh.mapped_argfunction {echo x; rwsh.mapped_argfunction<br>rwsh.argfunction {$1}}</pre>
There is a problem: if rwsh.argfunction was given directly as an
executable, since rwsh.argfunction is only recognized as an executable
name when the shell is trying to execute $1, it does not get
interpretted when there is any argument function for it to be replaced
with. &nbsp;As a result, only rwsh.mapped_argfunction is supported
as
the result of an interpretation<br>
<pre>rwsh.mapped_argfunction rwsh.mapped_argfunction xyy {$1 $2 {echo $1}}</pre>
will print<br>
<pre>xxy</pre>
</body>
</html>
......@@ -27,9 +27,6 @@ name to get the special meaning. Since they are not keywords, they can
be used as arguments to commands without the shell interfering. Of them
only rwsh.mapped\_argfunction can take arguments itself.
### rwsh.mapped\_argfunction
rwsh.mapped\_argfunction executes its argument function with the given
......@@ -52,7 +49,6 @@ interpretted for argument functions until they are run. For example
echo $*
rwsh.mapped_argfunction x $2 $3 {echo $*}}}
will output
1 2 3
......@@ -68,85 +64,70 @@ calls. Each time an argument script is interpretted
rwsh.unescaped\_argfunction is replaced by the current argument function
and rwsh.argfunction is replaced by rwsh.unescaped\_argfunction.
so if you type
<pre>.function fn {.function $* {rwsh.argfunction}}</pre>
.function fn {.function $* {rwsh.argfunction}}
the result of interpretting the command line results in<br>
the result of interpretting the command line results in
<pre>.function fn {.function $* {rwsh.unescaped\_argfunction}}</pre>
.function fn {.function $* {rwsh.unescaped_argfunction}}
which places ".function $* {rwsh.unescaped\_argfunction}" in the
executable\_map with name fn.<br>
executable\_map with name fn.
<br>
if you then type <br>
<pre>fn sel {echo $SELECT}</pre>
if you then type
fn sel {echo $SELECT}
the command is unchanged by interpretation, and the function that is
stored under fn gets interpretted to be<br>
<pre>.function sel {echo $SELECT}</pre>
stored under fn gets interpretted to be
.function sel {echo $SELECT}
If we had instead typed<br>
<pre>.function fn {.function $* {rwsh.unescaped\_argfunction}}</pre>
If we had instead typed
It would have been interpretted to result in<br>
.function fn {.function $* {rwsh.unescaped_argfunction}}
<pre>.function fn {.function $* {.function $* {rwsh.unescaped\_argfunction}}}</pre>
It would have been interpretted to result in
.function fn {.function $* {.function $* {rwsh.unescaped_argfunction}}}
The result would have been a function that takes an argument function
and defines a second function which, when run, would define a function
to execute the argument function that was passed to the first function.<br>
<br>
to execute the argument function that was passed to the first function.
The which command seeks to describe what is in the executable map in
the terms that you would use to put it there rather than what is
actually there. Thus<br>
<pre>which fn</pre>
actually there. Thus
prints out<br>
which fn
<pre>.function fn {.function $* {rwsh.argfunction}}</pre>
prints out
.function fn {.function $* {rwsh.argfunction}}
instead of what is stored, which is<br>
<pre>.function $* {rwsh.unescaped\_argfunction}</pre>
instead of what is stored, which is
.function $* {rwsh.unescaped_argfunction}
The which command also recognizes the names rwsh.mapped\_argfunction and
rwsh.argfunction to request the printing of the specified argument
function. In these cases the ".function rwsh.argfunction " part of the
print out is omitted for various reasons. For example, we could define
fn\_v<br>
<pre>fn fn\_v {.echo adding \ ; which rwsh.argfunction {rwsh.argfunction};<br>.echo \ to executable map as $1; fn $* {rwsh.argfunction}}</pre>
fn\_v
then running<br>
fn fn_v {.echo adding \ ; which rwsh.argfunction {rwsh.argfunction};
.echo \ to executable map as $1; fn $* {rwsh.argfunction}}
<pre>fn\_v sel {echo $SELECT}</pre>
then running
fn_v sel {echo $SELECT}
would print out<br>
would print out
<pre>adding {echo $SELECT} to executable map as sel</pre>
adding {echo $SELECT} to executable map as sel
<h3>rwsh.escaped\_argfunction</h3>
### rwsh.escaped_argfunction
Suppose you wanted to define a function fn-fn such that it defined a
function with the name of its first argument which was equivalent to
......@@ -154,32 +135,27 @@ function with the name of its first argument which was equivalent to
argument function, but not its own argument function, the new
function's argument
function. The solution is rwsh.escaped\_argfunction, which is replaced
by rwsh.argfunction when interpretted. fn-fn can be defined as follows:<br>
<pre>.function fn-fn {.function $1 {.function $* {rwsh.escaped\_argfunction}}}</pre>
by rwsh.argfunction when interpretted. fn-fn can be defined as follows:
<h3>argfunction call as the result of an interpretation</h3>
.function fn-fn {.function $1 {.function $* {rwsh.escaped_argfunction}}}
If you gave the command<br>
### argfunction call as the result of an interpretation
<pre>rwsh.mapped\_argfunction {echo x; rwsh.mapped\_argfunction<br>rwsh.argfunction {$1}}</pre>
If you gave the command
rwsh.mapped_argfunction {echo x; rwsh.mapped_argfunction
rwsh.argfunction {$1}}
There is a problem: if rwsh.argfunction was given directly as an
executable, since rwsh.argfunction is only recognized as an executable
name when the shell is trying to execute $1, it does not get
interpretted when there is any argument function for it to be replaced
with. &nbsp;As a result, only rwsh.mapped\_argfunction is supported
with. As a result, only rwsh.mapped\_argfunction is supported
as
the result of an interpretation<br>
<pre>rwsh.mapped\_argfunction rwsh.mapped\_argfunction xyy {$1 $2 {echo $1}}</pre>
the result of an interpretation
will print<br>
rwsh.mapped_argfunction rwsh.mapped_argfunction xyy {$1 $2 {echo $1}}
<pre>xxy</pre>
will print
</body>
</html>
xxy
This diff is collapsed.
This diff is collapsed.
......@@ -293,8 +293,7 @@ an unmodified selection. "..." and "[...]" have the same meaning, which
is to say that the first version above does not require two or more
arguments. "..." is currently not permitted to occur more than once in
a single function prototype. Note that a space is currently required
before
the "...", though I have seen man pages that do not do this.
before the "...", though I have seen man pages that do not do this.
### Whitespace within brackets
To simplify the parsing logic in the initial implementation, whitespace
......@@ -440,4 +439,3 @@ these errors, as would the following body.
if_only .var_exists -y {echo y flag passed}
if_only .test_not_empty $-? {echo other flags passed}
if_only .var_exists bar {echo $foo $bar $baz}
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en-us">
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>the selection</title>
</head>
<body>
Most of my time using a shell involves searching for some files and
then doing something with them. As a somewhat contrived example:<br>
<br>
ls /usr/local<br>
ls /usr/local/teTeX<br>
ls /usr/local/teTeX/include<br>
ls /usr/local/teTeX/include/kpathsea<br>
ls /usr/local/teTeX/include/kpathsea/c-*<br>
less /usr/local/teTeX/include/kpathsea/c-*<br>
<br>
then doing something with them. As a somewhat contrived example:
ls /usr/local
ls /usr/local/teTeX
ls /usr/local/teTeX/include
ls /usr/local/teTeX/include/kpathsea
ls /usr/local/teTeX/include/kpathsea/c-*
less /usr/local/teTeX/include/kpathsea/c-*
One might repetitively use cd in order to keep the paths shorter, or
use readline features to edit the previous command, but both distract
from what you're trying to do. For contrast, the corresponding, normal
rwsh sequence would be<br>
<br>
ls /usr/local/<br>
ls teTeX/<br>
ls include/<br>
ls kpathsea/<br>
ls c-*<br>
less<br>
<br>
rwsh sequence would be
ls /usr/local/
ls teTeX/
ls include/
ls kpathsea/
ls c-*
less
The argument to each command adds to the previous selection.
(The&nbsp;/
(The /
before "usr" clears the previous selection.) Finally, since the desired
files are
already selected, less does not need any arguments. This is
accomplished by each command being a shell function using selection set
and selection read. Both ls and less could be defined as follows:<br>
<br>
<pre>function ls {.selection_set s $1;&nbsp;/bin/ls -d @$s}<br><br>function less {.selection_set s $1;&nbsp;/usr/bin/less<br>@$s}<br></pre>
and selection read. Both ls and less could be defined as follows:
function ls {.selection_set s $1; /bin/ls -d @$s}
function less {.selection_set s $1; /usr/bin/less
@$s}
<br>
.selection_set takes a shell variable as its first argument, it uses
.selection\_set takes a shell variable as its first argument, it uses
the pattern in its second argument to augment the pattern held in the
shell variable. If no argument is given, then the existing pattern is
not changed. @ is the selection read operator, which converts the
......@@ -98,24 +48,19 @@ pattern into a list of the files matched by that pattern. @ can be
followed by a text string or $ and a shell variable. There is nothing
special about the variable s, except that both of the functions
use it to store the regular expression that they get their file list
from.<br>
<br>
from.
Since this accomplished using a normal shell variable, it is trivial to
implement commands like ftp's lls to explore a second selection, while
leaving the first unchanged. Since the filename matching patterns are
only treated specially by .selection_set and selection read, grep could
be defined by<br>
only treated specially by .selection\_set and selection read, grep could
be defined by
function grep {.set REGEX $1; .selection_set s $2 $*3; /usr/bin/grep
$REGEX @$s} The first argument is neither used by .selection_set nor
function grep {.set REGEX $1; .selection\_set s $2 $*3; /usr/bin/grep
$REGEX @$s} The first argument is neither used by .selection\_set nor
selection read
and so it can contain the wildcards that are used in filename patterns,
and&nbsp;pass unchanged to grep as long as it doesn't start with a
and pass unchanged to grep as long as it doesn't start with a
dollar sign or open brace. It is stored in the variable REGEX so that
another function, regrep, can be defined to grep for the same regular
expression in a different list of files. The second
......@@ -124,18 +69,20 @@ issue that this does not permit passing options to grep will be fixed
in a future release. The current workaround is to define a third shell
function, grepo, that takes options as its first argument, a regular
expression as its second argument, and optionally a list of files as
subsequent arguments.<br>
<br>
subsequent arguments.
The user interface of grep can be improved beyond removing the need to escape
the regular expression used for pattern matching. grep can be used to
modify the selection that will be used by subsequent commands. The
version that I have been using involves the following two functions:<br>
version that I have been using involves the following two functions:
<pre>.function grepl {<br>&nbsp; .set REGEX $1<br>&nbsp; .selection_set s $2 $*3<br>&nbsp; .set grep-sel $s<br>&nbsp; .selection_set grep-sel &amp;&amp;{&amp;{whichp grep} -l $REGEX @$s}$<br>&nbsp; echo $grep-sel}<br>.function gs {.set s $grep-sel}</pre>
.function grepl {
.set REGEX $1
.selection_set s $2 $*3
.set grep-sel $s
.selection_set grep-sel &&{&{whichp grep} -l $REGEX @$s}$
echo $grep-sel}
.function gs {.set s $grep-sel}
This sets the variable grep-sel to be the list of files that match the
pattern, if the list appears correct, then this can be made the active
......@@ -144,56 +91,34 @@ implementations: if efficiency is not an issue (you are always looking
at a small amount of data), then the statement that modifies grep-sel
can be added to normal grep commands, running grep twice. A more
complicated implementation could parse the output of grep to identify
the files mentioned, and set the variable accordingly.<br>
<br>
@ (selection read)<br>
the files mentioned, and set the variable accordingly.
@ (selection read)
<ul>
<li>Steps in a filename pattern are text separated by forward
slashes ("/").</li>
<li>If a step consists of "..", the effect is to undo the
* Steps in a filename pattern are text separated by forward
slashes ("/").
* If a step consists of "..", the effect is to undo the
previous
step. ("." is not handled specially, but works normally because it is
part of the file system. There is currently no way within a selection
read to refer to the file
link in each directory named "..".)</li>
<li>Otherwise a step may consist of any combination of text and
link in each directory named "..".)
* Otherwise a step may consist of any combination of text and
star
("*") characters. Text matches itself, a star matches zero or more of
any character in a filename. ("?" and other metacharacters are not
supported at this time.)</li>
<li>If there is an empty step (other than
after the final slash), that is if there&nbsp;are two consecutive
supported at this time.)
* If there is an empty step (other than
after the final slash), that is if there are two consecutive
forward slashes at any point in a filename pattern, the effect is to
move to the root of the file system. Thus @/usr/local//bin is
equivalent to @/bin.</li>
<li>If the end of a patten is an empty step (i.e. the pattern
equivalent to @/bin.
* If the end of a patten is an empty step (i.e. the pattern
ends
with a forward slash), the pattern is read as if the final step was a
star. Thus "@/usr/" is equivalent to "@/usr/*"</li>
</ul>
<br>
.selection_set &lt;variable&gt; &lt;pattern&gt;<br>
star. Thus "@/usr/" is equivalent to "@/usr/*"
.selection_set &lt;variable&gt; &lt;pattern&gt;
&lt;variable&gt;
is converted into a filename pattern and then &lt;pattern&gt;
......@@ -203,41 +128,25 @@ replaced by
the first part of &lt;pattern&gt;, unless
&lt;pattern&gt; begins with a
/. As with selection read, a pattern that ends with a / is read as if
it ended with /*. <br>
<ul>
<li>If &lt;variable&gt; contains "/usr/local", and
&lt;pattern&gt; is "bin", the result is "/usr/bin".&nbsp;</li>
it ended with /*.
<li>If &lt;variable&gt;
* If &lt;variable&gt; contains "/usr/local", and
&lt;pattern&gt; is "bin", the result is "/usr/bin".
* If &lt;variable&gt;
instead contains "/usr/local/", it is read as "/usr/local/*", and the
result is "/usr/local/bin".&nbsp;</li>
<li>If &lt;variable&gt; again contains
result is "/usr/local/bin".
* If &lt;variable&gt; again contains
"/usr/local", but &lt;pattern&gt; is "./bin", then the result
is
"/usr/local/bin".&nbsp;</li>
<li>If &lt;variable&gt;
contains&nbsp;"/usr/local/bin" and
"/usr/local/bin".
* If &lt;variable&gt;
contains "/usr/local/bin" and
&lt;pattern&gt; is "..", then the ".." replaces the "bin", and
the
effect of the ".." is to remove "local", resulting in "/usr".&nbsp;</li>
<li>Similarly if &lt;variable&gt; contains
effect of the ".." is to remove "local", resulting in "/usr".
* Similarly if &lt;variable&gt; contains
"/usr/local/bin" and &lt;pattern&gt; is "../bin", the result is
"/usr/bin".</li>
</ul>
"/usr/bin".
</body>
</html>
......@@ -6,6 +6,10 @@ objects = argm.o arg_script.o arg_spec.o builtin.o call_stack.o clock.o \
pipe_stream.o prototype.o selection.o substitution_stream.o \
variable_map.o
local_objects = rwsh_init.o
documentation = docs/argument_functions.html docs/builtins.html \
docs/function_prototypes_and_option_handling.html \
docs/internal_functions.html docs/introduction_and_philosophy.html \
docs/the_selection.html
CXX = g++-7
#CXX = g++
......@@ -17,9 +21,12 @@ rwsh: $(objects) $(local_objects)
$(CXX) $^ $(CXXFLAGS) $(LDLIBS) -o $@
librwsh.a: $(objects)
ar -rv $@ $(objects)
%.html: %.md
markdown $< >$@
# deps.mk: $(objects:o=cc) $(local_objects:o=cc)
# gcc >$@ -MM $^
include deps.mk
.PHONY: all clean dist
......@@ -43,4 +50,6 @@ cowboy-install: rwsh
ln -sf $(CURDIR)/rwshrc-default /etc/
ln -sf $(CURDIR)/rwshrc /etc/
ln -sf $(CURDIR)/rwsh /bin
docs: $(documentation)
docs-clean:
rm $(documentation)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment