Pocket Scheme

To evaluate a Scheme expression, enter it in the lower pane of the main window and issue the Tools - Evaluate command, or tap the green lambda on the command bar. Pocket Scheme will print the results of evaluating the expression in the upper pane of the main window.

You may also load expressions from a file, using either the Tools - Load... menu command or the Scheme procedures load or require. Pocket Scheme accepts both Unicode and ANSI sourcefiles. To create a Scheme file, use the Pocket Scheme Editor, or any other editor that can save a file as plain text.

To pause a running program momentarily, issue the Tools - Pause command, or tap the yellow hand on the command bar. To resume a paused program, issue Tools - Pause again. To stop a running program, use the Tools - Break command, or tap the red X on the command bar.

If you want to dismiss Scheme without terminating the session, press the cross-shaped button in the upper-right-hand screen corner, or simply select another program from the Pocket PC's Start menu. Any computation in progress will continue in the background, and Pocket Scheme will notify you once the computation completes.

To terminate Pocket Scheme, halting all computation and releasing all memory, use either the the Tools - Exit command or the Scheme procedure quit.

Entering Expressions

Pocket Scheme displays its data in two panes: a lower pane of editable text, used to input expressions into the interpreter, and an upper, read-only pane that displays the results of evaluating expressions. The Edit menu supports standard clipboard operations on each pane.

Each pane is fixed in size, occupying half of the available screen. Should this window layout not offer enough space to edit or view as desired, you can hide the status bar from View - Status, or specify that the input or output pane occupy the entire screen via View - Input - Full Screen or View - Output - Full Screen.

Pocket Scheme offers simple parenthesis matching in its input pane to assist in the input of complex S-expressions. The View - Match Paren command will move the input cursor to the parenthesis that matches the closest parenthesis; Edit - Select S-Expr does the same, but also selects the delimited S-expression, or the next greater surrounding S-expression if one is already selected. (Please note that neither function will work if the current selection is within a literal string constant.) These commands are also available from a context menu.

Setting View - Input - Smart Mode tells Pocket Scheme to perform some simple expression editing on your behalf. It will supply outermost parentheses, closing pending parentheses, and correct a few common handwriting recognition errors. Ordinarily Pocket Scheme does this automatically, but you can request a chance to review its changes by setting Review all Smart Mode changes on Tools - Configure - Screen.

The Edit - History commands put previously entered expressions into the lower pane. Use the green arrows on the command bar to scroll through this history.

Performance

The number of display calls that a Pocket Scheme program makes typically constrains its running speed. Eliminate all extraneous displayed information to increase program speed.

Escape continuations (bound by call/ec) are cheaper and faster than reentrant continuations (bound by call/cc). Use them in your code wherever you want a simple nonlocal exit.

Older Pocket PCs have very slow displays, especially when the output panes contain large amounts of data. On Tools - Configure - Screen, try clearing Wrap output to screen to make the display more responsive, and consider setting Truncate evaluation results, which will prevent a single verbose computation from choking the transcript with 50,000 characters all at once. Also, be sure to View - Output - Reset regularly.

Pocket Scheme Editor

Pocket Scheme includes a very simple text editor, which you can use to compose or edit small .scm files.

The Pocket Scheme Editor can balance parentheses in a manner similar to Pocket Scheme, and can indent or unindent blocks of text. In most other aspects it resembles Windows Notepad.

The View - Indentation dialog specifies how Pocket Scheme Editor will format typed expressions. Set Indent automatically to have the editor position the cursor correctly for each new line.

Use the File - Unicode switch to control whether the editor will save the current buffer in Unicode format.

Note that the Pocket Scheme Editor can only edit files of less than 32Kb in size. Also, its commands File - Open and File - Save only operate under the My Documents directory on your device or storage cards. To work around this shortcoming, open files from the File Explorer.

Debugging

The procedures trace and untrace implement call-tracing for user-defined functions. trace shadows a function with a shell that reports every call to and return from that function, while untrace removes the shadow from a function. Warning: calls to a traced procedure are no longer tail-recursive, even in tail position.

Printing call traces will greatly slow a program. To increase the speed of a deeply recursive traced procedure, hide the output window, either by tapping the taskbar rectangle to send Pocket Scheme to the background, or by tapping the little desktop box to bring the desktop to the foreground.

The procedure debug activates callstacks, a listing of pending procedure calls that Pocket Scheme will display when stopping with an error. For best performance, always leave this feature disabled (the default). Once code stops with an error, enable callstacks via (debug #t), then reevaluate the offending expression.

The procedure gc-verbose instructs the garbage collector whether to report its activity. Again, for best performance, always leave this feature disabled (the default). Enabling it via (gc-verbose #t) results in a pop-up window periodically appearing whenever Pocket Scheme recycles unused memory. (Note: this feature has been disabled for 1.3.) The procedures gc-stats and gc-reset-stats are also useful to this end.

Note: Tools - Break returns control to the topmost environment. It does not leave the user in the context of the interrupted evaluation, as the name might imply.

Scripting

In much the same fashion that a MS-DOS PC can run .BAT files via COMMAND.COM, or a Unix workstation can run shell scripts via /bin/sh, the Pocket PC can run Scheme "scripts" via Pocket Scheme.

To run a script, open it from the File Explorer. Pocket Scheme recognizes any file ending in the suffix .smd as its own, and will attempt to interpret the contents of that file as a Scheme program. See the description of the /r command line switch for an explanation of this mechanism. Note that double-tapping the icon of a .scm file will instead open that file in the Pocket Scheme Editor.

If the command line passes any arguments after the mandatory /r scriptname.smd, a script can access those arguments through its *argv* global. E.g., the invocation pscheme.exe /r "\My Documents\mail.smd" root@x.com would run the Scheme program \My Documents\mail.smd, setting the global symbol *argv* to the list ("\\My Documents\\mail.smd" "root@x.com").

By default, a script that stops with an error leaves Scheme in interactive mode, while a script that completes successfully closes the Scheme window when finished.

You may switch away from a running script at any time. If it needs input, it will notify you. Otherwise, it will continue running until it completes. To return to a running script, open it again from File Explorer.

Configuration

The Tools/Configure command evokes a dialog used to configure the language interpreter. Leave a field empty to retain the interpreter's default configuration.

Directories

Home path defines Pocket Scheme's initial starting directory. This defaults to the application installation directory.
Library path defines a directory automatically searched by the procedures require and find-library-file. This defaults to the application installation directory.
Initialization file names a file of definitions to evaluate when first starting Pocket Scheme. If this is a complete pathname, e.g., \My Documents\init.scm, then it will set the current working directory as well. Otherwise the filename is interpreted relative to the installation directory.

Memory

Total heap specifies the maximum amount of memory that the heap of cons cells may occupy, in megabytes (Mb). Each cell requires 16 bytes of memory. Pocket Scheme will not actually allocate this memory until the need for it arises.

Screen

Use ClearType tells Pocket Scheme to try to use ClearType in its output.
Wrap output to screen suppresses the horizontal scrollbar in output panes. This gives a tidier screen, but can be slow on older devices or with much output.
Truncate evaluation results limits the amount of text that a single pass of the REPL will leave in the output transcript.
Smart Mode at startup specifies the initial setting of View - Input - Smart Mode.
Review all Smart Mode changes displays any automatic Smart Mode changes to the user, who must approve them by tapping the Eval button again. If this is clear, Pocket Scheme will automatically submit Smart Mode edits on the user's behalf.

Any changes made in this dialog will not take effect until the next Scheme session. You must force Pocket Scheme to exit (via Tools - Exit) and restart it rather than dismissing it with the cross button in the upper right-hand corner.

Command line switches

The Pocket Scheme executable file, pscheme.exe, accepts a number of command-line switches that change its behavior. Most of these override the settings of Tools - Configure.

Switch Effect

/! Displays the configuration dialog.

/? Displays information about the program.

/n Suppress the introductory copyright window.

/r scmfile Evaluate every expression in the named file, then close the Scheme window. Pass all subsequent command-line switches and arguments in the *argv* variable. (Use this to implement scripts in Pocket Scheme.)

/i initfile Specifies an initialization file to load at startup. If this is a fully qualified path, this also sets the initial current working directory, which otherwise defaults to the application installation directory.

/d librarypath Overrides the library directory for require. (By default this is \Program Files\Pocket Scheme, a directory not easily accessible to P/PC applications.)

/h heaplimit Heap size, as described under Configuration. Be careful when experimenting with this.

Switch	Effect
/!	Displays the configuration dialog.
/?	Displays information about the program.
/n	Suppress the introductory copyright window.
/r scmfile	Evaluate every expression in the named file, then close the Scheme window. Pass all subsequent command-line switches and arguments in the `argv` variable. (Use this to implement scripts in Pocket Scheme.)
/i initfile	Specifies an initialization file to load at startup. If this is a fully qualified path, this also sets the initial current working directory, which otherwise defaults to the application installation directory.
/d librarypath	Overrides the library directory for `require`. (By default this is \Program Files\Pocket Scheme, a directory not easily accessible to P/PC applications.)
/h heaplimit	Heap size, as described under Configuration. Be careful when experimenting with this.

Keyboard shortcuts

If your Pocket PC has a keyboard, then you may find the following keyboard shortcuts convenient.

In both Pocket Scheme and Pocket Scheme Editor:

Press	To
Ctrl+H	View this Help file
Ctrl+Z	Undo last change to lower pane
Ctrl+X	Cut selection from lower pane to clipboard
Ctrl+C	Copy selection from pane to clipboard
Ctrl+V	Paste clipboard to lower pane
Del	Clear selection from lower pane
Ctrl+A	Select all text in pane
Ctrl+B	Jump to matching parenthesis in edited text
Ctrl+Shift+B	Jump to matching parenthesis in edited text, selecting the delimited expression

In Pocket Scheme only:

Press	To
Ctrl+L	Load a Scheme sourcefile
Ctrl+G	Evaluate the current buffer
Ctrl+Q	Break into a running program
Ctrl+E	Toggle keyboard focus between panes
Ctrl+R	View previous expression in evaluation history
Ctrl+Shift+R	View next expression in evaluation history
Ctrl+S	Pause a running program

In Pocket Scheme Editor only:

Press	To
Ctrl+O	Open a new file
Ctrl+S	Save the current file
Ctrl+F	Search for a word
Ctrl+Shift+F	Search for the next occurrence of the word
Tab	Move the cursor one tab stop to the right, inserting spaces
Shift+Tab	Move the cursor one tab stop to the left
Ctrl+Tab	Shift a block of text one tab stop to the right
Ctrl+Shift+Tab	Shift a block of text one tab stop to the left