jdb / wordish Goto Github PK
View Code? Open in Web Editor NEWParse a recorded interactive shell session, execute the commands and compare the outputs.
Parse a recorded interactive shell session, execute the commands and compare the outputs.
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: :: ~$ 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: :: ~$ ( 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. :: ~$ 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 [#]_. :: ~$ 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. :: ~$ 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: :: ~$ 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.
I think the requires
line should be replaced with install_requires
At least that worked for me.
(wordish)(master โ =)[~/projects/wordish]$ git diff
diff --git a/setup.py b/setup.py
index 7bb0493..5391b84 100644
--- a/setup.py
+++ b/setup.py
@@ -13,7 +13,7 @@ setup(
"commands compare the outputs"),
license = 'GPL',
- requires = [ 'docutils (>=0.5)' ],
+ install_requires = [ 'docutils >= 0.5' ],
long_description = """
Wordish is a script which executes a shell session parsed from a
[~]$ mkvirtualenv wordish
New python executable in wordish/bin/python
Installing setuptools, pip...done.
(wordish)[~]$ pip install wordish
Downloading/unpacking wordish
Downloading wordish-1.0.2.tar.gz (53kB): 53kB downloaded
Running setup.py (path:/home/richard/.virtualenvs/wordish/build/wordish/setup.py) egg_info for package wordish
warning: no files found matching '*' under directory 'html/'
warning: no files found matching '*' under directory 'examples/'
Installing collected packages: wordish
Running setup.py install for wordish
warning: no files found matching '*' under directory 'html/'
warning: no files found matching '*' under directory 'examples/'
Successfully installed wordish
Cleaning up...
(wordish)[~]$ python -m wordish
Traceback (most recent call last):
File "/usr/lib64/python2.7/runpy.py", line 162, in _run_module_as_main
"__main__", fname, loader, pkg_name)
File "/usr/lib64/python2.7/runpy.py", line 72, in _run_code
exec code in run_globals
File "/home/richard/.virtualenvs/wordish/lib/python2.7/site-packages/wordish.py", line 164, in <module>
from docutils import core
ImportError: No module named docutils
BTW Thanks for wordish
. Are you still maintaining it? We're experimenting to see if it can be used to test our tutorial:
So we may have a few more bugs and fixes to contribute.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.