Package: wordish
Wordish is a script which executes a shell session parsed from a
documentation in the restructured text[1]format, then tests and builds a
report of the execution. To mark up shell code in an article,wordishuses the custom directivesourcecode, with the rquired
argumentsh. When presented with an article:wordishfilters out the text which is not marked withsourcecode,then, separates the blocks of shell codes betweencommandsandoutputs:wordishconsumes the prompt, parses for the newline which ends
command,then parses for the prompt which ends the output,Example:.. sourcecode:: sh

   ~$ echo "hello world"   # Mmmh, insightful comment
   hello worldThis simply renders like:~$ echo "hello world"   # Mmmh, insightful comment
hello worldThecommandstarts after the prompt (“~$ “) and continues until the
first newline is found in the source code block. Here, it is just
after the wordcomment. The command isecho "hello world" # Mmmh, insightful commentThe output is the text block found until the next
prompt: this ishello world. There aretwopossible prompts:~$, and~#. Both are required to be followed by a space are are
treated the same.Note: the newlines which are nested in curly brackets or parentheses arenotinterpreted as anend of commandcharacter. Shells do the same:
curly brackets are used to define functions and parentheses makes the
nested command to be interpreted in a subprocess shell. The two
following examples from the introduction make it clear:~$ (
echo $((1+1)) )
2

~$ sum () {
echo $(( $1 + $2 ))
}The first command isecho$((1+1))in a subproces, and it’s output
is2. The second command is the definition of a function namedsumand has no output. Defining functions sometimes clarify the
intent in subsequent uses of the function. For functions to be re-used,
the state of the shell must be kept between each snippets.wordishkeep a connection with the sameshellsubprocess (bashis used)
for the duration of the article.~$ sum 42 58
3See how the output is obviously incorrect? we will see later how this
is reported.When the output can not be completely predicted, such as when
displaying$RANDOM, or displaying the size of a partitions in
bytes, there is a handy wildcard pattern which can be used:.... It matches everything like.*in regexp[2].~$ echo "a random number: " $RANDOM
...One last thing, if a command does not exit gracefully,wordishprecautiously aborts, refusing to execute commands on the system under
test which is in an undefined state.wordishdisplays the remaining
unexecuted commands.~$ What have the Romans ever done for us
aqueduct? roads? wine !

~$ echo "Bye bye"
Bye byeThis introduction is embedded in the wordish module as the
docstring. Just runwordishwith no argument to get the example
report of this article:~$ python -m wordish
Trying:      echo "hello world"   # Mmmh, insightful comment...
Expecting:   hello world
ok

Trying:      (
echo $((1+1)) )
Expecting:   2
ok

Trying:      sum () {
echo $(( $1 + $2 ))
}
Expecting:
ok

Trying:      sum 42 58
Expecting:   3
Failed, got: 100, 0

Trying:      echo "a random number: " $RANDOM
Expecting:   ...
ok

Trying:      What have the Romans ever done for us
Expecting:   aqueduct? roads? wine !
Failed, got: /bin/bash: line 19: What: command not found, 127

Command aborted, bailing out
Untested command:
     echo "Bye bye"
     python -m wordish
6 tests found.
4 tests passed, 2 tests failed.There is another example real worldarticlewhich is also included in
the sources distribution, and tested before each release. This is the
article which prompted the need for the development ofwordish.[1]This syntax can be seen as light and readable version of html
or latex, and was designed with the experience of existing Wiki
syntaxes. The Sphinx project has a niceintroductiononrst,
the reference documentation ishere.[2]Regexp are not directly used so that the various special regexp
characters do not need to be escaped.