Parses a shell session, execute the commands, compare the outputs, build a report
Project description
Wordish is a script which executes a shell session parsed from a
documentation in the restructured text [#]_ format, then tests and builds a
report of the execution. To mark up shell code in an article,
*wordish* uses the custom directive ``sourcecode``, with the rquired
argument ``sh``. When presented with an article:
#. *wordish* filters out the text which is not marked with
``sourcecode``,
#. then, separates the blocks of shell codes between *commands* and
*outputs*:
#. *wordish* consumes 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 world
This simply renders like:
.. sourcecode:: sh
~$ echo "hello world" # Mmmh, insightful comment
hello world
The *command* starts after the prompt ("~$ ") and continues until the
first newline is found in the source code block. Here, it is just
after the word ``comment``. The command is ``echo "hello world" # Mmmh,
insightful comment`` The output is the text block found until the next
prompt: this is ``hello world``. There are **two** possible 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 are
**not** interpreted as an *end of command* character. 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:
.. sourcecode:: sh
~$ (
echo $((1+1)) )
2
~$ sum () {
echo $(( $1 + $2 ))
}
The first command is ``echo $((1+1))`` in a subproces, and it's output
is ``2``. The second command is the definition of a function named
``sum`` and 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. *wordish*
keep a connection with the same *shell* subprocess (*bash* is used)
for the duration of the article.
.. sourcecode:: sh
~$ sum 42 58
3
See 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 [#]_.
.. sourcecode:: sh
~$ echo "a random number: " $RANDOM
...
One last thing, if a command does not exit gracefully, *wordish*
precautiously aborts, refusing to execute commands on the system under
test which is in an undefined state. *wordish* displays the remaining
unexecuted commands.
.. sourcecode:: sh
~$ What have the Romans ever done for us
aqueduct? roads? wine !
~$ echo "Bye bye"
Bye bye
This introduction is embedded in the wordish module as the
docstring. Just run *wordish* with no argument to get the example
report of this article:
.. sourcecode:: sh
~$ 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 world article_ which is also included in
the sources distribution, and tested before each release. This is the
article which prompted the need for the development of *wordish*.
.. _article: http://jdb.github.com/sources/lvm.txt
.. [#] 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 nice introduction_ on *rst*,
the reference documentation is here_.
.. _introduction: http://sphinx.pocoo.org/rest.html
.. _here: http://docutils.sourceforge.net/rst.html#user-documentation
.. [#] Regexp are not directly used so that the various special regexp
characters do not need to be escaped.
documentation in the restructured text [#]_ format, then tests and builds a
report of the execution. To mark up shell code in an article,
*wordish* uses the custom directive ``sourcecode``, with the rquired
argument ``sh``. When presented with an article:
#. *wordish* filters out the text which is not marked with
``sourcecode``,
#. then, separates the blocks of shell codes between *commands* and
*outputs*:
#. *wordish* consumes 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 world
This simply renders like:
.. sourcecode:: sh
~$ echo "hello world" # Mmmh, insightful comment
hello world
The *command* starts after the prompt ("~$ ") and continues until the
first newline is found in the source code block. Here, it is just
after the word ``comment``. The command is ``echo "hello world" # Mmmh,
insightful comment`` The output is the text block found until the next
prompt: this is ``hello world``. There are **two** possible 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 are
**not** interpreted as an *end of command* character. 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:
.. sourcecode:: sh
~$ (
echo $((1+1)) )
2
~$ sum () {
echo $(( $1 + $2 ))
}
The first command is ``echo $((1+1))`` in a subproces, and it's output
is ``2``. The second command is the definition of a function named
``sum`` and 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. *wordish*
keep a connection with the same *shell* subprocess (*bash* is used)
for the duration of the article.
.. sourcecode:: sh
~$ sum 42 58
3
See 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 [#]_.
.. sourcecode:: sh
~$ echo "a random number: " $RANDOM
...
One last thing, if a command does not exit gracefully, *wordish*
precautiously aborts, refusing to execute commands on the system under
test which is in an undefined state. *wordish* displays the remaining
unexecuted commands.
.. sourcecode:: sh
~$ What have the Romans ever done for us
aqueduct? roads? wine !
~$ echo "Bye bye"
Bye bye
This introduction is embedded in the wordish module as the
docstring. Just run *wordish* with no argument to get the example
report of this article:
.. sourcecode:: sh
~$ 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 world article_ which is also included in
the sources distribution, and tested before each release. This is the
article which prompted the need for the development of *wordish*.
.. _article: http://jdb.github.com/sources/lvm.txt
.. [#] 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 nice introduction_ on *rst*,
the reference documentation is here_.
.. _introduction: http://sphinx.pocoo.org/rest.html
.. _here: http://docutils.sourceforge.net/rst.html#user-documentation
.. [#] Regexp are not directly used so that the various special regexp
characters do not need to be escaped.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
wordish-1.0.0beta.tar.gz
(10.0 kB
view hashes)