byexample passes the environment variables to the
interpreters and they are available from the examples and modules.
This is the default and quite handy if you want to make your documentation configurable for scripting.
Let’s say you have a shell example:
$ if [ "$PWD" != "/root" ]; then > echo "You must run this script from /root" > fi You must run this script from /root
Pasting a captured environment variable
But what if we want to capture their value and paste them as part of an example?
Consider an example where a Python example depends on the current directory.
Because you could be running
byexample from anywhere, such example
would likely fail: the output is not deterministic.
However you could paste the environment variable
$PWD which has
the current directory as the expected output.
$ cat test/ds/capture-env.doc # byexample: +rm= -tags >>> import os >>> assert '<PWD>' == os.getcwd() # byexample: +paste
You just need to pass which variables from the environment will be in
the clipboard of
byexample so they can be pasted.
$ byexample -l python --capture-env-var PWD test/ds/capture-env.doc <...> [PASS] Pass: 2 Fail: 0 Skip: 0
You can capture as many environment variables as you want:
$ byexample -l python --capture-env-vars PWD,HOME,USER test/ds/capture-env.doc <...> [PASS] Pass: 2 Fail: 0 Skip: 0
Conditional execution on a captured environment variable
Perhaps the most useful combination is with conditionals.
Consider the following toy-example that it is executed unless the given environment variable is passed:
$ cat test/ds/capture-bomb.doc # byexample: +rm= $ echo "Booom!" # byexample: +unless=bomb_disabled The bomb should not explode!
Running the example with an empty or unset variable
make the example to run and fail (as expected, the bomb exploded).
$ echo $bomb_disabled # empty, it is not set $ byexample -l shell --capture-env-var bomb_disabled test/ds/capture-bomb.doc <...> Expected: The bomb should not explode! Got: Booom! <...> [FAIL] Pass: 0 Fail: 1 Skip: 0
But setting anything to the variable we can skip the execution of the example.
$ export bomb_disabled=some $ byexample -l shell --capture-env-var bomb_disabled test/ds/capture-bomb.doc <...> [PASS] Pass: 0 Fail: 0 Skip: 1
Note: in both cases
bomb_disabledwas put in the clipboard, this is required because
+unlesswill complain if the variable is not there (empty or not empty).
byexample 10.1.0. This feature is marked as