diff options
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | docs/reference/index.rst | 5 | ||||
| -rw-r--r-- | docs/reference/repl.rst | 207 |
3 files changed, 212 insertions, 6 deletions
@@ -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. - diff --git a/docs/reference/index.rst b/docs/reference/index.rst index fae0a219a2..35030b65dd 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -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:: diff --git a/docs/reference/repl.rst b/docs/reference/repl.rst new file mode 100644 index 0000000000..c03cbfd388 --- /dev/null +++ b/docs/reference/repl.rst @@ -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. + |