docs: Add docs about REPL paste-mode and Control-C
This commit is contained in:
Dave Hylands
Damien George
parent
98fb0bf68a
commit
a9f3030371
@ -151,9 +151,3 @@ correct permissions. Try then:
|
||||
|
||||
$ sudo dfu-util -a 0 -d 0483:df11 -D build-PYBV10/firmware.dfu
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
You can find information about the documentation in the
|
||||
[docs/README.md](https://github.com/micropython/micropython/blob/master/docs/README.md) file.
|
||||
|
||||
|
||||
@ -9,6 +9,11 @@ documentation at
|
||||
Differences to standard Python as well as additional features of
|
||||
MicroPython are described in the sections here.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
repl.rst
|
||||
|
||||
.. only:: port_pyboard
|
||||
|
||||
.. toctree::
|
||||
|
||||
207
docs/reference/repl.rst
Normal file
207
docs/reference/repl.rst
Normal file
@ -0,0 +1,207 @@
|
||||
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: ::
|
||||
|
||||
def foo():
|
||||
print('This is a test to show paste mode')
|
||||
print('Here is a second line')
|
||||
foo()
|
||||
|
||||
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: ::
|
||||
|
||||
raise SystemExit
|
||||
|
||||
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
|
||||
|
||||
PYB: sync filesystems
|
||||
PYB: soft reboot
|
||||
MicroPython v1.5-51-g6f70283-dirty on 2015-10-30; PYBv1.0 with STM32F405RG
|
||||
Type "help()" for more information.
|
||||
>>> dir()
|
||||
['__name__', 'pyb']
|
||||
>>>
|
||||
|
||||
The special variable _ (underscore)
|
||||
-----------------------------------
|
||||
|
||||
When you use the REPL, you may perfom computations and see the results.
|
||||
MicroPython stores the results of the previous statment in the variable _ (underscore).
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user