ShowEval
========
The ``showeval`` directive creates an animated sequence.
Synopsis
--------
.. code-block:: rst
.. showeval:: unique_id
:trace_mode: boolean
+ --- Content area ---+
| Pre-requisite information and code
| ~~~~
| some {{code}} followed by {{replacement code}}
| more {{code}} followed by {{replacement code}} ##with optional comment
+ --------------------+
All prerequisite information that should be displayed above the animation,
such as variable declaration, are separated from the step strings by ``~~~~``.
The step animations follow the ``~~~~`` and are written one per line.
Required Arguments
------------------
unique id
A unique identifier after a space and the ``::`` in the directive.
Valid identifiers must not contain spaces.
You should also avoid the characters `` ` ``, ``,``, ``:``, and ``*``.
content area
The ``showeval`` directive should contain at least two steps to be useful.
The steps section has special formatting requirements:
- Each step must be wholly contained on a line, one animation step per line.
- Blank lines are OK.
- Use double curly braces: ``{{`` and ``}}`` to mark
text replaced during an animation step.
Only 1 set of replacement text per line.
- The end braces of the original text and start of the replacement braces
must be exactly ``}}{{`` - no spaces are permitted.
The braces surround the part of the line that should be replaced,
followed by the replacement text delimited using double curly braces.
To add a comment that will appear in a div beside the animation,
denote that at the end of the step where you would like it to appear with ``##``.
trace_mode
``Boolean``. If ``true``, will print out a new line for each step of the animation.
If ``false``, will display and animate a single line,
overwriting the previous animation, during each animation step.
Optional Arguments
------------------
No optional arguments are defined for this directive.
Languages supported
-------------------
The ``showeval`` directive is language agnostic.
Nothing is actually executed or interpreted.
It is up to the animation author to ensure the syntax and grammar within an animation
makes sense - no syntax checking is performed.
Sphinx configuration options
----------------------------
No sphinx configuration options exist for this directive.
Internationalization
....................
tbd
Known limitations
-----------------
No syntax highlighting is performed for any language.
This directive is intended to help explore the inner workings of a small chunk of code.
To show the more complex interactions between variables and functions,
consider using :doc:`codelens`.
.. include:: html_content.txt
A bug in ``showeval`` prevents it from working correctly in a :doc:`tab` directive.
Every animation line renders twice.
Examples
--------
The first example shows joining two arrays with showeval in trace mode
and then shows the exact same example in replace mode.
Showing the source code with ``:tracemode: true``.
This source code:
.. literalinclude:: se_examples/showeval_ex_py.txt
:language: rst
Created this example:
.. include:: se_examples/showeval_ex_py2.txt
This example shows the exact same code as the previous example,
but with ``:tracemode: false``.
.. showeval:: showEval_false
:trace_mode: false
eggs = ['dogs', 'cats', 'moose']
~~~~
''.join({{eggs}}{{['dogs', 'cats', 'moose']}}).upper().join(eggs)
{{''.join(['dogs', 'cats', 'moose'])}}{{'dogscatsmoose'}}.upper().join(eggs)
{{'dogscatsmoose'.upper()}}{{'DOGSCATSMOOSE'}}.join(eggs)
'DOGSCATSMOOSE'.join({{eggs}}{{['dogs', 'cats', 'moose']}})
{{'DOGSCATSMOOSE'.join(['dogs', 'cats', 'moose'])}}{{'dogsDOGSCATSMOOSEcatsDOGSCATSMOOSEmoose'}}
Using comments
..............
Comments are optional and appear after ``##`` on any animation line.
A comment is displayed as soon as an animation line is loaded,
**before** the animation executes.
When the *Next Step* button is pressed, the comment is removed.
This source code:
.. literalinclude:: se_examples/showeval_ex_cpp.txt
:language: rst
Created this example:
.. include:: se_examples/showeval_ex_cpp2.txt