Phemto

A python editor that's tiny for tiny environments

pye

User's Guide

Allows editing files directly on python based target boards, using a terminal emulator such as MSWindows putty, Mac os terminal or Linux terminal.

Operations include:

open (existing or new file), save, quit, …
goto line#, find, replace, …
create bookmark, go to previous/next bookmark.
cut, copy, paste, redraw, undo, redo, …
indent, un-indent, comment, …
tab, backtab and scrolling.

Features

Action keys include: ^f find, ^n next, ^z undo, ^c copy, ^v paste, …
Special keys, include: [home], [end], [PgUp], …
Lines can be joined with cursor at the end of the line using delete or
with cursor at the beginning with backspace.
enter key inserts or splits a line with automatic indentation.
Command history permits multiple undo / redo and go to changes.
Status line shows row, column, etc.
Multiple files can be edited simultaneously with multiple windows.
Mouse scrolling and setting the cursor.
Can be used with data files or program code.
Online help

The editor operates in insert mode, that is, characters typed are inserted, control+key, alt+key and ␛,key are commands.
Cursor Keys, home, end, page^ … work as you would expect.

Installation

Transfer to the target board:

The code:
- pye.mpy (frozen bytecode for Pyboard, ESP8266, ESP32, PyCom devices, Maixpy …) or
- compiled byte code which reduces start-up time and saves memory and file space or
- pye.py source
The file h for online help in an alternate window(optional).

Starting pye

From python REPL prompt:
>>>> from pye import pye
>>>> [result =] pye([ object_1, object_2, …[, tabsize=n][, undo=n ] )

If object_n is a string ( example "main.py" it's a file or a directory (example "/flash") .
- For a file, the content will be loaded.
  If the file does not exist an empty edit window is opened and it is given that name.
- For a directory, the list of filenames will be loaded to the edit window.
```
 Directory
          /flash
          boot.py
          main.py
```
- For pye() the list of files in current directory is used.
- For a list of strings, (example ( ["start","stuff","end"]) they will be loaded into the editing window
If object_n is not a string nor a list of strings, for example: pye( var ), ( where var is not defined ) an empty window is opened.

tabsize =n Tab step (integer). The default is 4.
undo=n history size (integer). The minimum size is 4.

Keystroke commands (Operations)

Notations:

Hold the ctrl key while pressing the next key OR
Press the ␛ key, then the next key. Not with special keys i.e. [home],…

Hold the alt key while pressing the next key

Function Keys

Open a new file to a window ^o
Save ␛ s
Quit a window or the line edit mode. ^q
␛ ␛
Previous window ^[PgUp]
Next window ^[PgDn]
^W

Inserting

Characters typed are inserted
Insert spaces to the next tab stop. ( Default tab stops are every 4 columns)
Indent the selection. [tab]
line break at the cursor position. Auto-indent depends on setting. [enter]

Movement
go to:
Top of the file ^t
Left to the start of the actual or previous symbol skipping over to the previous line. ^←
Start-of-line OR start-of-text [home]
Right behind the next symbol or line end, wrapping over to the next line. ^→
End-of-code OR End-of-line [end]
Line # ^g
Bottom of the file ^b
^[end]
previous Change
next ~[home]
~[end]
Bookmark a location in any window. ~[ins]
previous Bookmark
next ~[PgUp]
~[PgDn]

Match bracket the cursor is on.
Bracket pairs are ( ), [ ], { } and < > ^k

Current line or selected up / down with the cursor ^↑ / ^↓
Cursor up / down a screen [PgUp] / [PgDn]
Scroll the window up / down ^↑ / ^↓

Selecting text
Start selection
Once selecting is started it can be extended by moving the cursor.
The selection is effected by Delete, Backspace, Copy, Cut, Paste, Tab, Backtab, Find, Save and Replace.
End selecting by pressing ^L or ^space or an operation(copy, delete,...). shift →
shift ←
^L
^space
Select previous / next word or extend the Selection. ^shift ← / ^shift →
Copy selection to the clipboard ^c
Cut selection to the clipboard. The selection is cleared.
This implements the "Cut & Paste" feature. ^x
Paste the clipboard at the cursor position.
If text is selected, it is replaced.
In the line edit mode: paste the item under the cursor. ^v

Deleting
Selection [del]
[backspace]
Char left of the cursor.
Join to the previous line if cursor is at the beginning of the line.
[backspace]
Char under (before) the cursor.
Join with the next line if cursor is at the end of the line
With auto-indent, delete the leading spaces of the line. [del]
Word under the cursor or spaces up to the next non-space. ^[del]
Spaces back to the previous tab stop or non-space [backtab]
Line shift[del]
Un-indent a single line or multiple selected lines. ^u
[backtab]

Finding
Find a regular expression.
For example ^def^† finds def at the beginning of a line.
Skips a selection.
Case sensitivity is set by ^a. Stops at the end of file.
The search string is remembered. ^f
Next find ^n
Find and replace. Optionally: yes, all, no(skip), quit
With a selection only the selection is searched and all only applies to the selection. ^r

Additional Commands
Redraw the screen and display file size and free space
*main.py Row: 5/116 Col: 30. 2524KB Memory free. File 213KB, 3121KB free. ^e
Undo the last change(s). ^z
Redo the operation undone by Undo immediately after Undo(s).
Any change to the text invalidates the redo history. ^y
Comment / Uncomment a line or selected area.
That is: insert / remove the comment character(s) (default '#') ^p
^_
Adjust Attributes that is: those provided when pye was started.
Enter y, n, a number or several characters in comma separated fields (example:y,n,4,#,n)
Empty field leaves the value unchanged.

The defaults are :

auto-indent: y

search case sensitive: n

tab-size: 4 ; that is a tab stop occurs every 4 columns

comment string #

write-tabs: n

^a

Mouse Actions
Set the cursor. Button 1
Set / Clear highlighting. Double click
Button 1
Find and open a directory window button 2
Search button1
Open file button1
Scroll Up / Down the screen content by 3 lines per tick. Scroll Wheel

Function	Keys
Open a new file to a window	^o
Save	␛ s
Quit a window or the line edit mode.	^q ␛ ␛
Previous window	^[PgUp]
Next window	^[PgDn] ^W
Inserting
Characters typed are inserted
Insert spaces to the next tab stop. ( Default tab stops are every 4 columns) Indent the selection.	[tab]
line break at the cursor position. Auto-indent depends on setting.	[enter]
Movement go to:
Top of the file	^t
Left to the start of the actual or previous symbol skipping over to the previous line.	^←
Start-of-line OR start-of-text	[home]
Right behind the next symbol or line end, wrapping over to the next line.	^→
End-of-code OR End-of-line	[end]
Line #	^g
Bottom of the file	^b ^[end]
previous Change next	~[home] ~[end]
Bookmark a location in any window.	~[ins]
previous Bookmark next	~[PgUp] ~[PgDn]
Match bracket the cursor is on. Bracket pairs are ( ), [ ], { } and < >	^k
Current line or selected up / down with the cursor	^↑ / ^↓
Cursor up / down a screen	[PgUp] / [PgDn]
Scroll the window up / down	^↑ / ^↓
Selecting text
Start selection Once selecting is started it can be extended by moving the cursor. The selection is effected by Delete, Backspace, Copy, Cut, Paste, Tab, Backtab, Find, Save and Replace. End selecting by pressing ^L or ^space or an operation(copy, delete,...).	shift → shift ← ^L ^space
Select previous / next word or extend the Selection.	^shift ← / ^shift →
Copy selection to the clipboard	^c
Cut selection to the clipboard. The selection is cleared. This implements the "Cut & Paste" feature.	^x
Paste the clipboard at the cursor position. If text is selected, it is replaced. In the line edit mode: paste the item under the cursor.	^v
Deleting
Selection	[del] [backspace]
Char left of the cursor. Join to the previous line if cursor is at the beginning of the line.	[backspace]
Char under (before) the cursor. Join with the next line if cursor is at the end of the line With auto-indent, delete the leading spaces of the line.	[del]
Word under the cursor or spaces up to the next non-space.	^[del]
Spaces back to the previous tab stop or non-space	[backtab]
Line	shift[del]
Un-indent a single line or multiple selected lines.	^u [backtab]
Finding
Find a regular expression. For example ^def^† finds def at the beginning of a line. Skips a selection. Case sensitivity is set by ^a. Stops at the end of file. The search string is remembered.	^f
Next find	^n
Find and replace. Optionally: `yes, all, no`(skip)`, quit` With a selection only the selection is searched and `all` only applies to the selection.	^r
Additional Commands
Redraw the screen and display file size and free space `*main.py Row: 5/116 Col: 30. 2524KB Memory free. File 213KB, 3121KB free.`	^e
Undo the last change(s).	^z
Redo the operation undone by Undo immediately after Undo(s). Any change to the text invalidates the redo history.	^y
Comment / Uncomment a line or selected area. That is: insert / remove the comment character(s) (default '#')	^p ^_
Adjust Attributes that is: those provided when pye was started. Enter y, n, a number or several characters in comma separated fields (example:y,n,4,#,n) Empty field leaves the value unchanged. The defaults are : auto-indent: y search case sensitive: n tab-size: 4 ; that is a tab stop occurs every 4 columns comment string # write-tabs: n	^a
Mouse Actions
Set the cursor.	Button 1
Set / Clear highlighting.	Double click Button 1
Find and open a directory window	button 2
Search	button1
Open file	button1
Scroll Up / Down the screen content by 3 lines per tick.	Scroll Wheel

Additional notes

Status line

*main.py Row: 5/116 Col: 30
^- asterisk indicates window contents have been changed.

For online help use ^oh to open the file h in a new window and use ^w to switch between helpfile and editing window.

Opening Files

When opening a new window the filename will be prompted for.
If the name is empty, an empty window will be opened.
If the file cannot be loaded (for example it does not exist), an empty window with that name will be opened.
If the name is a directory a list of filenames will be loaded.

Exiting

When saving, the content is written to a temporary file (basename + “.pyetmp”) then it is renamed to the filename.
When saving an unnamed window, the filename will be prompted for.
If the filename is invalid, the temporary file will have the content.
After saving the window will be named as the saved file, which acts as Save-as.

For quit, if the edited text was changed, confirmation is asked for.

When the last window is closed, the pye terminates providing the return value:

Editing Return Value
  file name of the file
  list list
  directory name of the directory

Editing	Return Value
file	name of the file
list	list
directory	name of the directory

Options

The option to replace all sequences of spaces by tabs, tab size 8. If the initial file contained tab characters, this is the default. When reading files, tabs are replaced by spaces, tab size 8, and white space at the end of a line is discarded.

The undo stack size per window can be set pye() default: micro 50, PC systems 500.

PC Usage

The PC version can be called from the command line with:
pye.py [filename , … ]

Using python3 pye.py [filename , … ] content can be redirected or pipe'd to pye.

Internals

Uses stdin/stdout on the MicroPython boards.

Board specific information

WiPy1: only works only on a Telnet session with the UART connection closed.
ESP8266: only the frozen bytecode variant can be used.

Memory Considerations

The size of a file that can be edited is limited by the memory of the target board.
Files up to about 13kb on ESP8266 and 68kb on PyBoard should fit.
REDRAW updates available memory show in the status line. In addition to the file, clipboard and especially undo consume memory.
The undo stack can be limited in the call to pye using undo=n.
The clipboard size can be reduced by copying a single line into it.

When saving a file on PyBoard, the changes may not be visible in the file system of a connected PC until you disconnect and reconnect the Pyboard drive.
See also the related discussion in the MicroPython Forum.

Saving to the internal flash file system of PyBoard is slow.

In some cases, Escape seems to lock the keyboard, it unlocks by typing any alpha character.

Terminal Emulators

Windows
- Putty does not report mouse actions, and does not return code for shift-arrow keys.
- TeraTerm, IVT terminal and Xsh20 report the mouse click, but not the scroll wheel actions.
- ZOC reports mouse positions constantly, and
  sends no key codes for Home, End, PgUp, PGDn and Del.
- PowerVT sends no key codes for Home, End, PgUp, PGDn and Del.
- Hyperterminal's VT100 emulation is poor.
Linux
- Gnome terminal sometimes does not send the first mouse wheel code, after the pointer was moved into the window.
- Mate and XFCE4 have slightly different keyboard mappings.
- Picocom sometimes sends Linux Terminal codes.
Mac OS
- terminal

See Pyboard_Editor.doc in GitHub for additional details.

DGerman@Real-World-Systems.com version 1.4, 8/10/22 for pye version 2.77