.. toctree::

:maxdepth: 1

repl.rst

The MicroPython Interactive Interpreter Mode (aka REPL)

This section covers some characteristics of the MicroPython Interactive

Interpreter Mode. A commonly used term for this is REPL (read-eval-print-loop)

which will used to refer to this interactive prompt.

Auto-indent

When typing python statements which end in a colon (for example if, for, while)

then the prompt will change to three dots (...) and the cursor will be indented

by 4 spaces. When you press return, the next line will continue at the same

level of indentation for regular statements or an additional level of indentation

where appropriate. If you press the backspace key then it will undo one

level of indentation.

If your cursor is all the way back at the beginning, pressing RETURN will then

execute the code that you've entered. The following shows what you'd see

after entering a for statement (the underscore shows where the cursor winds up):

>>> for i in range(3):

... _

If you then enter an if statement, an additional level of indentation will be

provided:

>>> for i in range(30):

... if i > 3:

... _

Now enter ``break`` followed by RETURN and press BACKSPACE:

>>> for i in range(30):

... if i > 3:

... break

... _

Finally type ``print(i)``, press RETURN, press BACKSPACE and press RETURN again:

>>> for i in range(30):

... if i > 3:

... break

... print(i)

...

0

1

2

3

>>>

Auto-completion

While typing a command at the REPL, if the line typed so far corresponds to

the beginning of the name of something, then pressing TAB will show

possible things that could be entered. For example type ``m`` and press TAB

and it should expand to ``machine``. Enter a dot ``.`` and press TAB again. You

should see something like:

>>> machine.

__name__ info unique_id reset

bootloader freq rng idle

sleep deepsleep disable_irq enable_irq

Pin

The word will be expanded as much as possible until multiple possibilities exist.

For example, type ``machine.Pin.AF3`` and press TAB and it will expand to

``machine.Pin.AF3_TIM``. Pressing TAB a second time will show the possible

expansions:

>>> machine.Pin.AF3_TIM

AF3_TIM10 AF3_TIM11 AF3_TIM8 AF3_TIM9

>>> machine.Pin.AF3_TIM

Interrupting a running program

You can interupt a running program by pressing Ctrl-C. This will raise a KeyboardInterrupt

which will bring you back to the REPL, providing your program doesn't intercept the

KeyboardInterrupt exception.

For example:

>>> for i in range(1000000):

... print(i)

...

0

1

2

3

...

6466

6467

6468

Traceback (most recent call last):

File "<stdin>", line 2, in <module>

KeyboardInterrupt:

>>>

Paste Mode

If you want to paste some code into your terminal window, the auto-indent feature

will mess things up. For example, if you had the following python code: ::

and you try to paste this into the normal REPL, then you will see something like

this:

>>> def foo():

... print('This is a test to show paste mode')

... print('Here is a second line')

... foo()

...

Traceback (most recent call last):

File "<stdin>", line 3

IndentationError: unexpected indent

If you press Ctrl-E, then you will enter paste mode, which essentially turns off

the auto-indent feature, and changes the prompt from ``>>>`` to ``===``. For example:

>>>

paste mode; Ctrl-C to cancel, Ctrl-D to finish

=== def foo():

=== print('This is a test to show paste mode')

=== print('Here is a second line')

=== foo()

===

This is a test to show paste mode

Here is a second line

>>>

Paste Mode allows blank lines to be pasted. The pasted text is compiled as if

it were a file. Pressing Ctrl-D exits paste mode and initiates the compilation.

Soft Reset

A soft reset will reset the python interpreter, but tries not to reset the

method by which you're connected to the MicroPython board (USB-serial, or Wifi).

You can perform a soft reset from the REPL by pressing Ctrl-D, or from your python

code by executing: ::

For example, if you reset your MicroPython board, and you execute a dir()

command, you'd see something like this:

>>> dir()

['__name__', 'pyb']

Now create some variables and repeat the dir() command:

>>> i = 1

>>> j = 23

>>> x = 'abc'

>>> dir()

['j', 'x', '__name__', 'pyb', 'i']

>>>

Now if you enter Ctrl-D, and repeat the dir() command, you'll see that your

variables no longer exist:

.. code-block:: python

So you can use the underscore to save the result in a variable. For example:

>>> 1 + 2 + 3 + 4 + 5

15

>>> x = _

>>> x

15

>>>

Raw Mode

Raw mode is not something that a person would normally use. It is intended for

programmatic use. It essentially behaves like paste mode with echo turned off.

Raw mode is entered using Ctrl-A. You then send your python code, followed by

a Ctrl-D. The Ctrl-D will be acknowledged by 'OK' and then the python code will

be compiled and executed. Any output (or errors) will be sent back. Entering

Ctrl-B will leave raw mode and return the the regular (aka friendly) REPL.

The ``tools/pyboard.py`` program uses the raw REPL to execute python files on the

MicroPython board.