\section{Standard Module \module{cmd}}

\stmodindex{cmd}

\label{module-cmd}

The \code{Cmd} class provides a simple framework for writing

line-oriented command interpreters. These are often useful for

test harnesses, administrative tools, and prototypes that will

later be wrapped in a more sophisticated interface.

\begin{classdesc}{Cmd}{}

A \class{Cmd} instance or subclass instance is a line-oriented

interpreter framework. There is no good reason to instantiate Cmd

itself; rather, it's useful as a superclass of an interpreter class

you define yourself in order to inherit Cmd's methods and encapsulate

action functions.

\end{classdesc}

\subsection{Cmd Objects}

\label{Cmd-objects}

A \class{Cmd} instance has the following methods:

\begin{methoddesc}{cmdloop}{intro}

Repeatedly issue a prompt, accept input, parse an initial prefix off

the received input, and dispatch to action methods, passing them the

remainder of the line as argument.

The optional argument is a banner or intro string to be issued before the

first prompt (this overrides the \member{intro} class member).

If the \module{readline} module is loaded, input will automatically

inherit Emacs-like history-list editing (e.g. Ctrl-P scrolls back to

the last command, Ctrl-N forward to the next one, Ctrl-F moves the

cursor to the right non-destructively, Ctrl-B moves the cursor to the

left non-destructively, etc.).

An end-of-file on input is passed back as the string "EOF".

An interpreter instance will recognize a command name \code{foo} if

and only if it has a method named \method{do_foo}. As a special case,

a line containing only the character `?' is dispatched to the method

\method{do_help}. As another special case, a line containing only the

character `!' is dispatched to the method \method{do_shell} (if such a method

is defined).

All subclasses of \class{Cmd} inherit a predefined \method{do_help}.

This method, called with an argument \code{bar}, invokes the

corresponding method \method{help_bar}. With no argument,

\method{do_help} lists all available help topics (that is, all

commands with corresponding \code{help_} methods), and also lists any

undocumented commands.

\end{methoddesc}

\begin{methoddesc}{onecmd}{str}

Interpret the argument as though it had been typed in in

response to the prompt.

\end{methoddesc}

\begin{methoddesc}{emptyline}{}

Method called when an empty line is entered in response to the prompt.

If this method is not overridden, it repeats the last nonempty command

entered.

\end{methoddesc}

\begin{methoddesc}{default}{line}

Method called on an input line when the command prefix is not

recognized. If this method is not overridden, it prints an

error message and returns.

\end{methoddesc}

\begin{methoddesc}{precmd}

Hook method executed just before the input prompt is issued. This method is

a stub in \class{Cmd}; it exists to be overridden by subclasses.

\end{methoddesc}

\begin{methoddesc}{postcmd}

Hook method executed just after a command dispatch is finished. This

method is a stub in \class{Cmd}; it exists to be overridden by

subclasses.

\end{methoddesc}

\begin{methoddesc}{preloop}

Hook method executed once when \method{cmdloop()} is called. This method is

a stub in \class{Cmd}; it exists to be overridden by subclasses.

\end{methoddesc}

\begin{methoddesc}{postloop}

Hook method executed once when \method{cmdloop()} is about to return. This

method is a stub in \class{Cmd}; it exists to be overridden by

subclasses.

\end{methoddesc}

Instances of \class{Cmd} subclasses have some public instance variables:

\begin{memberdesc}{prompt}

The prompt issued to solicit input.

\end{memberdesc}

\begin{memberdesc}{identchars}

The string of characters accepted for the command prefix.

\end{memberdesc}

\begin{memberdesc}{lastcmd}

The last nonempty command prefix seen.

\end{memberdesc}

\begin{memberdesc}{intro}

A string to issue as an intro or banner. May be overridden by giving

the \method{cmdloop()} method an argument.

\end{memberdesc}

\begin{memberdesc}{doc_header}

The header to issue if the help output has a section for documented commands.

\end{memberdesc}

\begin{memberdesc}{misc_header}

The header to issue if the help output has a section for miscellaneous

help topics (that is, there are \code{help_} methods withoud corresponding

\code{do_} functions).

\end{memberdesc}

\begin{memberdesc}{undoc_header}

The header to issue if the help output has a section for undocumented

commands (that is, there are \code{do_} methods withoud corresponding

\code{help_} functions).

\end{memberdesc}

\begin{memberdesc}{ruler}

The character used to draw separator lines under the help-message

headers. If empty, no ruler line is drawn. It defaults to "=".

\end{memberdesc}

\section{Standard Module \module{multifile}}

\stmodindex{multiFile}

\label{module-multifile}

The \code{MultiFile} object enables you to treat sections of a text

file as file-like input objects, with EOF being returned by

\code{readline} when a given delimiter pattern is encountered. The

defaults of this class are designed to make it useful for parsing

MIME multipart messages, but by subclassing it and overriding methods

it can be easily adapted for more general use.

\begin{classdesc}{MultiFile}{fp[, seekable=1]}

Create a multi-file. You must instantiate this class with an input

object argument for MultiFile to get lines from, such as as a file

object returned by \code{open}.

MultiFile only ever looks at the input object's \code{readline},

\code{seek} and \code{tell} methods, and the latter two are only

needed if you want to random-access the multifile sections. To use

MultiFile on a non-seekable stream object, set the optional seekable

argument to 0; this will avoid using the input object's \code{seek}

and \code{tell} at all.

\end{classdesc}

It will be useful to know that in MultiFile's view of the world, text

is composed of three kinds of lines: data, section-dividers, and

end-markers. MultiFile is designed to support parsing of

messages that may have multiple nested message parts, each with its

own pattern for section-divider and end-marker lines.

\subsection{MultiFile Objects}

\label{MultiFile-objects}

A \class{MultiFile} instance has the following methods:

\begin{methoddesc}{push}{str}

Push a boundary string. When an appropriately decorated version of

this boundary is found as an input line, it will be interpreted as a

section-divider or end-marker and passed back as EOF. All subsequent

reads will also be passed back as EOF, until a \method{pop} removes

the boundary a or \method{next} call reenables it.

It is possible to push more than one boundary. Encountering the

most-recently-pushed boundary will return EOF; encountering any other

boundary will raise an error.

\end{methoddesc}

\begin{methoddesc}{readline}{str}

Read a line. If the line is data (not a section-divider or end-marker

or real EOF) return it. If the line matches the most-recently-stacked

boundary, return EOF and set \code{self.last} to 1 or 0 according as

the match is or is not an end-marker. If the line matches any other

stacked boundary, raise an error. If the line is a real EOF, raise an

error unless all boundaries have been popped.

\end{methoddesc}

\begin{methoddesc}{readlines}{str}

Read all lines, up to the next section. Return them as a list of strings

\end{methoddesc}

\begin{methoddesc}{read}{str}

Read all lines, up to the next section. Return them as a single

(multiline) string. Note that this doesn't take a size argument!

\end{methoddesc}

\begin{methoddesc}{next}{str}

Skip lines to the next section (that is, read lines until a

section-divider or end-marker has been consumed). Return 1 if there

is such a section, 0 if an end-marker is seen. Re-enable the

most-recently-pushed boundary.

\end{methoddesc}

\begin{methoddesc}{pop}{str}

Pop a section boundary. This boundary will no longer be interpreted as EOF.

\end{methoddesc}

\begin{methoddesc}{seek}{str, pos, whence=0}

Seek. Seek indices are relative to the start of the current section.

The pos and whence arguments are interpreted as for a file seek.

\end{methoddesc}

\begin{methoddesc}{next}{str}

Tell. Tell indices are relative to the start of the current section.

\end{methoddesc}

\begin{methoddesc}{is_data}{str}

Return true if a 1 is certainly data and 0 if it might be a section

boundary. As written, it tests for a prefix other than '--' at start of

line (which all MIME boundaries have) but it is declared so it can be

overridden in derived classes.

Note that this test is used intended as a fast guard for the real

boundary tests; if it always returns 0 it will merely slow processing,

not cause it to fail.

\end{methoddesc}

\begin{methoddesc}{section_divider}{str}

Turn a boundary into a section-divider line. By default, this

method prepends '--' (which MIME section boundaries have) but it is

declared so it can be overridden in derived classes. This method

need not append LF or CR-LF, as comparison with the result ignores

trailing whitespace.

\end{methoddesc}

\begin{methoddesc}{end_marker}{str}

Turn a boundary string into an end-marker line. By default, this

method prepends '--' and appends '--' (like a MIME-multipart

end-of-message marker) but it is declared so it can be be overridden

in derived classes. This method need not append LF or CR-LF, as

comparison with the result ignores trailing whitespace.

\end{methoddesc}

Finally, \class{MultiFile} instances have two public instance variables:

\begin{memberdesc}{level}

\end{memberdesc}

\begin{memberdesc}{last}

1 if the last EOF passed back was for an end-of-message marker, 0 otherwise.

\end{memberdesc}

Example:

\begin{verbatim}

\end{verbatim}