When you type something in a console or in an interactive interpreter, what you type is echoed so you can see what you are typing.
byexample disables this so it can capture the output of an example
without having the typed example mixed with it.
However not all the interpreters honor this and they may leave turned on the echo anyway.
For example this shell example uses
stty to re-enable the echoing:
$ echo "normal output" normal output $ stty echo $ echo "normal output" echo "normal output" normal output
byexample 11.0.0: since
11.0.0, the echo is disabled before executing each example. This makes the execution more robust against changes in the terminal settings. Before
11.0.0the echo was disabled only on the interpreter startup only. You may change this using
-x-turn-echo-offbut be careful.
Having to expect what you typed is ugly and confusing for your readers.
byexample has the experimental ability to suppress the echoing with
$ echo "normal output" # byexample: +force-echo-filtering normal output
You can pass
+force-echo-filtering from the command line to take effect
on all the examples of all the languages but this is not encouraged
byexample 11.0.0 you can enforce the echo filtering
per language with
$ byexample -l shell,python -o "+force-echo-filtering-for=shell" test/ds/echo-filtering-required.md # byexample: +timeout 8 <...> File test/ds/echo-filtering-required.md, <...> seconds [PASS] <...>
+force-echo-filtering-for from the
command line is not allowed.
$ byexample -l shell,python -o "+force-echo-filtering-for=shell +force-echo-filtering" test/ds/echo-filtering-required.md # byexample: +timeout 8 <...> argument +force-echo-filtering: not allowed with argument +force-echo-filtering-for <...>
byexample 11.0.0: before
11.0.0, the only way to apply the filtering to all the examples was using
+force-echo-filteringfrom the command line but unfortunately that affects all the rest of interpreters that may not require the filtering.
11.0.0you should use
+force-echo-filtering-forin the command line to affect all the examples of the language(s) selected and use
+force-echo-filteringonly when you want to enable the filtering in a particular example.
Limitations and restrictions
Forcing a filtering comes with some restrictions:
- the example will use a full terminal emulation,
in other words
- due the emulation, your output will be limited by the geometry of the emulated terminal; you may have to set this too at the begin of your document.
- the echo must exist otherwise the filter may filter part of your output.
- it is an experimental feature.
If possible, try to disable the echo from the interpreter itself and
+force-echo-filtering as a last resort.
For example, in
python you can use
termios to control the echoing:
>>> import sys >>> from termios import tcgetattr, tcsetattr, TCSANOW, ECHO >>> def set_echo_mode(enable): ... fd = sys.stdin.fileno() ... attrs = tcgetattr(fd) ... ... if enable: ... attrs |= ECHO ... else: ... attrs &= ~ECHO ... ... tcsetattr(fd, TCSANOW, attrs) >>> set_echo_mode(False) <...>