byexample can use different emulation modes to process the output of the
byexample uses a dumb terminal (
is fast and works well in most cases.
But you can change this to disable emulation with
to enable full ANSI terminal emulation with
In this mode,
byexample emulates a very simple terminal, processing
only the white spaces.
It does not have the concept of a cursor, does not interpret escape codes and does not break lines automatically.
Even if a geometry is defined
+geometry, the dumb terminal
does not force any boundaries: the following example
will print a string longer than the width of the terminal.
>>> print("aaaabbbb" * 8) # byexample: +geometry 24x32 aaaabbbbaaaabbbbaaaabbbbaaaabbbbaaaabbbbaaaabbbbaaaabbbbaaaabbbb
White space processing
The dumb terminal removes any trailing whitespace, converts tabs to spaces and standardizes the new lines.
This suits most examples, reducing the need to add tabs into the
examples or requiring the
normalization of whitespace
>>> print("\tfoo\tbar\nbaz\tsaz \rtaz") foo bar baz saz taz
If you need to check whitespace characters, you can use
disable terminal emulation.
+term=as-is is activated the output is passed as is without
any modification except for standardization of new lines.
It can be useful in some special cases to check white spaces that are removed by the dumb or ANSI terminals.
>>> print("\tfoo\tbar\nbaz\tsaz \rtaz") # byexample: +term=as-is foo bar baz saz taz
Some programs may need a real terminal or at least an emulated ANSI terminal.
byexample can emulate one capable of interpreting and emulating
all the control sequences and escape codes using
Note: terminal emulation is not fully supported in
Python 2.7. It should work but using a modern
Pythonversion is recommended.
If you have an example that is printing text with color, you will probably see something like:
$ echo -e "\033[31mmessage in red\033[0m" <...>[31mmessage in red<...>[0m
To get rid of those weird symbols you can enable terminal emulation:
$ echo -e "\033[31mmessage in red\033[0m" # byexample: +term=ansi message in red
Keep in mind that an emulated terminal will honor its own boundaries or geometry: if an example prints a string longer than the width of the terminal, the string will spawn multiple lines (a newline is added automatically).
>>> print("aaaabbbb" * 8) # byexample: +term=ansi +geometry 24x32 aaaabbbbaaaabbbbaaaabbbbaaaabbbb aaaabbbbaaaabbbbaaaabbbbaaaabbbb
This is especially useful to work with
ncurses or other advanced programs.
Some applications use advanced terminal features (like the ones
ncurses) and require a terminal emulator.
Examples of this are programs like
$ less test/ds/python-tutorial.v2.md # byexample: +term=ansi +rm= +stop-on-timeout This is a 101 Python tutorial The following is an example written in Python about arithmetics ``` >>> from __future__ import print_function >>> 1 + 2 3 ``` The next examples show you about complex numbers in Python ``` >>> 2j * 2 4j >>> 2j + 4j 6j ``` <...>(END)
Try the above example without
+term=ansiand see what happens.
byexample will not emulate pagination. When the output is larger than
the height of the terminal, lines that scroll off the top are discarded.
The following example prints more lines than are available in the terminal so only the last lines are shown.
>>> for i in range(1,33): # byexample: +term=ansi +geometry=5x80 ... print("line %i" % i) line 29 line 30 line 31 line 32
If this is a problem change the geometry:
increase the count of rows that the terminal has with
Emulation is typically 3 times slower than the normal mode
Keep that in mind and try to not enable it by default.