/
README.txt
154 lines (111 loc) · 4.41 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
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.