Terminal Emulation
byexample
can use different emulation modes to process the output of the
runners.
By default byexample
uses a dumb terminal (+term=dumb
) which
is fast and works well in most cases.
But you can change this to disable emulation with +term=as-is
or
to enable full ANSI terminal emulation with +term=ansi
.
Dumb terminal
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
with +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
with +norm-ws
.
>>> print("\tfoo\tbar\nbaz\tsaz \rtaz")
foo bar
baz saz
taz
If you need to check whitespace characters, you can use +term=as-is
to
disable terminal emulation.
As-is terminal
When +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
ANSI terminal
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 +term=ansi
.
Note: terminal emulation is not fully supported in
Python 2.7
. It should work but using a modernPython
version is recommended.
Removing color
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
Terminal boundaries
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.
ncurses support
Some applications use advanced terminal features (like the ones
that use ncurses
) and require a terminal emulator.
Examples of this are programs like less
, more
, top
and man
.
$ 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=ansi
and see what happens.
Pagination
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 +geometry
.
Performance
Emulation is typically 3 times slower than the normal mode
(+term=dumb
).
Keep that in mind and try to not enable it by default.