Implementor 1.3 Manual



Implementor was designed and programmed by Donnie Russell. Design suggestions
were kindly contributed by Roger Firth, who also submitted bug reports and
tested the editor on several operating systems.



Introduction

Implementor is a text editor designed primarily for the Interactive Fiction
programmer. Most major IF languages are supported, and additional languages
can be added by the user with minimal effort. While not a full-featured IDE,
Implementor has the basic features necessary for writing, compiling, and
debugging source code, as well as executing program code, using only a few
easy-to-remember keystrokes. Version 1.3 added support for regular
expressions and spellchecking.



License

This program is freeware. You may use it freely and give it to your friends.



Operating System Requirements

DOS Version

DOS running on at least a 386 processor

Windows Version

Windows 95, 98, ME, XP



Memory Requirements

The more the better, but 64 MB should be the absolute minimum.



Features and Specifications

Implementor is designed to handle very large text files with Unix, PC, or
Macintosh line breaks.

Text file sizes are not limited in terms of physical size, but the maximum
line length or number of lines should not exceed the number 2147483647.

An unlimited number of files may be edited simultaneously, but each object
consumes memory and cpu resources. Memory used for the Undo/Redo feature can
quickly fill up available resources, so caution should be used when editing
very large files (greater than 10 megabytes).

The DOS and Windows versions both support long file names; however, the DOS
version only supports long file names while running under Windows.

The DOS version supports a graphical mouse pointer when running full-screen.
The editing of ANSI characters is supported in the DOS version, but they will
display as incorrect symbols due to the OEM character set used by DOS. In
addition, under DOS, some ANSI characters are used to draw the graphical mouse
pointer.

Text files must be in 8-bit ANSI format. Unicode is not supported.

The Windows version uses the following registry key:
"HKEY_CURRENT_USER/Software/DonnieRussell/Implementor" to store window
positioning data.



The Implementor Window

Windows Version

Implementor's main window consists of the following:

A title bar which can be used to move, minimize, maximize, or close the main
window.

Two scroll bars at the bottom and right side of the window. The contents of
the currently active object (see below) are scrolled horizontally and
vertically using the main window scroll bars.

The client area of the window is the workspace. Objects within the workspace
work very similarly to ordinary windows.

DOS Version

The main screen consists only of a workspace.



The Object Bar

The object bar, at the top of the workspace, displays all objects present in
the workspace. Arrows appear at the left and right ends of the object bar when
additional objects are displayed offscreen. Left-clicking the arrows scrolls
the object bar in the corresponding direction. The currently active object
(see below) is highlighted, and left-clicking a non-active object on the
object bar activates it.



The Object Frame

Objects have a frame around their perimeter which is color coded to the
information contained within. The default colors are:

Grey
An inactive object. Left-clicking anywhere inside activates the object.

Black
A file browser object that displays the current directory. This object is
always open. Clicking the 'C' (close) button refreshes the directory listing.

Blue-Green
An editable text file.

Red
A read-only text file. The text is unchangeable.

Left-clicking on the 'C' (close) button closes the object.

Left-clicking on the 'S' (split) button splits the object's view pane into two
parts. Clicking the 'S' again recombines the panes back into one. Clicking on
each pane activates it, and further movement of the cursor applies only to the
active pane. The currently active pane is indicated by the cursor and view
coordinates displayed just below it.

Left-clicking and dragging the left or top side of the object frame moves the
object around the workspace, and double-left-clicking the same area maximizes
or restores the object. A maximized object fills the workspace and cannot be
moved or resized.

Left-clicking and dragging the right or bottom side of the object frame
resizes the object.



The Object View Pane

Left-clicking within the pane places the cursor at the selected position.

Left-clicking and dragging selects text. Dragging the mouse pointer to the
edges of the frame scrolls the view in the corresponding direction.

Double-left-clicking selects a word, and triple-left-clicking selects a line.
Holding the left mouse button down on the last click and moving the mouse
initiates a drag operation.



Cursor Controls

Holding down the left [Shift] key while pressing the following keys will cause
text to be selected while the cursor moves.

[Left]
Moves the cursor one character to the left. If the cursor is at the beginning
of the line, it moves up to the end of the previous line.

[Ctrl+Left]
Moves the cursor one word to the left. The cursor scans backwards across
multiple lines until it finds a word.

[Right]
Moves the cursor one character to the right. If the cursor is at the end of
the line, it moves down to the beginning of the next line.

[Ctrl+Right]
Moves the cursor one word to the right. The cursor scans forwards across
multiple lines until it finds a word.

[Up]
Moves the cursor up one line. The horizontal position of the cursor is
maintained as closely as possible.

[Down]
Moves the cursor down one line. The horizontal position of the cursor is
maintained as closely as possible.

[Page Up]
Moves the cursor up one page. A page is the height of the current object pane.
The horizontal position of the cursor is maintained as closely as possible.

[Page Down]
Moves the cursor down one page. A page is the height of the current object
pane. The horizontal position of the cursor is maintained as closely as
possible.

[Home]
Alternately moves the cursor to the first non-whitespace character, or
beginning, of the line.

[Ctrl+Home]
Moves the cursor to the beginning of the text.

[End]
Moves the cursor to the end of the line.

[Ctrl+End]
Moves the cursor to the end of the text.



Accessing the Main Menu

The main menu can be accessed in two ways: by right-clicking on the workspace,
or by pressing the [F8] key. The main menu is closed by left-clicking outside
the menu, right-clicking on the workspace, or by pressing the [Esc] key. A
menu item can be selected by left-clicking on the desired item, or by pressing
the [Cursor] and [Enter] keys.



Main Menu Options

When the menu is closed, the specified key (if any) executes the desired
option.

New [Ctrl+N]
Creates a new object with the temporary name "New#####.ext", where ##### is a
number and "ext" is the file extension specified in the configuration file.
When the object is saved, the editor will ask for a filename.

Open [Ctrl+O]
Opens an object from text contained in the file specified. If no path is
entered, the current directory is assumed.

Close
Closes the currently active object. If the object is modified, the editor will
ask if it should save the object to a file. The file browser can never be
closed.

Close All
Closes all objects except the file browser. The user will have the opportunity
to save each modified object before it is closed.

Quit [Ctrl+Q]
This option saves the workspace (if the configuration specifies this), closes
all objects (saving each object first, if the user chooses), and finally
closes the application.

Save [Ctrl+S]
If the currently active object is modified, the editor saves the object to a
file. There is no confirmation prompt except when the file was created with
the New option.

Save As
Saves the object to the specified file. If the file already exists, the editor
prompts the user for confirmation.

Save All [Ctrl+Shift+S]
For each modified object, the editor saves the object to a file. There is no
confirmation prompt except when the file was created with the New option.

Undo [Ctrl+Z]
The last change made to the text is taken back.

Redo [Ctrl+Y]
After at least one change is taken back, this option returns the text to its
original state before the last undo.

Cut [Ctrl+X]
The selected text is copied to the clipboard and deleted from the object. In
the DOS version, the text is stored in memory, not in the Windows clipboard.

Copy [Ctrl+C]
Copies the selected text to the clipboard. In the DOS version, the text is
stored in memory, not in the Windows clipboard.

Paste [Ctrl+V]
Pastes the text stored in the clipboard into the object at the current cursor
position. If text is already selected, it is replaced.

Select All [Ctrl+A]
All text in the object is selected, and the cursor is positioned at the end of
the text.

Find [F5]
An input prompt is displayed that allows the user to enter a search parameter.
If text is selected when the Find option is chosen, and the regular expression
option is turned off, the text will be copied to the "Find Text" parameter.
Three options can be toggled by either clicking the 'X' boxes or by pressing
[F1], [F2] and [F3]. If "Match Case" is selected, all alphabetical characters
are matched taking case into account. If "Match Whole Words" is selected, the
search parameter will only be matched with whole words in the text, not word
fragments. This option does nothing if the search parameter contains
non-alphanumeric characters, such as spaces. If "Regular Expression" is
selected, regular expressions and replacement expressions are used for
searching and replacing. See the file "re.txt" for more information. Searching
starts at the current cursor position. Click "Proceed" (or press [Enter]) to
start the search. Click "Cancel" (or press [Esc]) to cancel it.

Find Next [Ctrl+F]
Finds the next occurrence of the search parameter following the cursor without
prompting.

Replace [F6]
Similar to the Find option, but replaces the next occurrence of the search
parameter following the cursor with the specified replacement parameter. Click
the 'X' box next to "Replace All", or press [F4], to replace all occurrences
in the entire text. Click on the "Find Text" or "Replace With" parameters, or
press [Tab] to toggle between them, and enter the required data.

Replace Next [Ctrl+R]
Finds and replaces the next occurrence of the search parameter following the
cursor with the replacement parameter without prompting.

Go To Line [Ctrl+G]
Places the cursor on the line specified by the user.

Invert Case [Ctrl+K]
Upper Case [Ctrl+U]
Lower Case [Ctrl+L]
Changes the case of all selected alphabetic characters. The selection size
cannot exceed 4096 characters.

Increase Indent [Ctrl+P]
Reduce Indent [Ctrl+Shift+P]
Increases or decreases the indentation of all selected lines by the amount
specified in the configuration file. Tabs will be used to fill the indented
whitespace if this option is also specified in the configuration. If no lines
are selected, only the line the cursor is currently on will be affected. The
affected lines remain selected after the operation.

Comment [Ctrl+T]
Uncomment [Ctrl+Shift+T]
Adds/removes the comment symbol to/from the beginning of all selected lines.
The type of comment symbol used is specified in the configuration file. If no
lines are selected, only the line the cursor is currently on will be affected.
The affected lines remain selected after the operation.

Reformat
Limits the line width of all selected lines by inserting line breaks and
removing trailing whitespace. The maximum line width is specified by the user
at a prompt. Line breaks are inserted between words unless the word is larger
than what the maximum line width allows; in the latter case, the word is
broken. Lines split from an indented line are indented the same amount unless
the indent size is greater than the reformat width. If no lines are selected,
only the line the cursor is currently on will be affected.

ANSI Code
Allows the user to enter ANSI characters not available in the standard ASCII
character set. Left-click on the desired character, or use the cursor keys and
[Enter]. Right-click or press [Esc] to cancel.

Run Command #1 [Alt+1]
Run Command #2 [Alt+2]
Run Command #3 [Alt+3]
Run Command #4 [Alt+4]
Runs the command specified in the configuration file. After it finishes,
output and error objects will appear at the bottom of the workspace if any
information is available. If a command is currently running, attempting to run
another will have no effect. The user will be prompted for confirmation before
the editor closes if a command is still running.

Previous Error [F3]
Next Error [F4]
After running a command that compiles source code, error messages may be
displayed in the output and error objects at the bottom of the workspace. The
mode of interpreting errors is specified in the configuration file. Selecting
these options allows the user to browse through the listed errors. The source
code file specified in the error is opened or, if already opened, the relevant
object is made active, and the cursor is placed on the relevant line.
Double-clicking the error message has the same effect.

Select Object [F2]
Selecting this option opens the object selector. Left-clicking an object title
or pressing the [Up] or [Down] keys selects the currently active object.
Double-left-clicking an object title, right-clicking, pressing [Enter], or
pressing [Esc] closes the object selector. Clicking the top or bottom of the
object selector scrolls the titles up or down.

Check Spelling [Ctrl+W]
Starting at the top of the text of the active object, each word is compared
with words in the main and user dictionaries. If a word is not found, a prompt
appears with correction options. Ten suggestions for the correct word are
given; left-clicking the suggestion or pressing one of the digits between '0'
and '9' copies the suggestion to the edit box. The first suggestion is
automatically placed there. The corrected word can be edited with the normal
text-editing keys. Right-clicking the edit box clears it. Pressing [Enter]
corrects the word in the text. Pressing [Space] ignores the current word.
Pressing [Tab] ignores all further occurrences of the current word. Pressing
[+] adds the current word to the user dictionary. Pressing [Esc] exits the
spell check operation.

Help [F1]
If this option is selected, the "help.txt" file in the configuration directory
is opened and the word currently under the cursor, preceded by the characters
"*>", is located in the text of the help file. The cursor is placed at the
section relevant to the desired keyword, if it exists. Pressing the [ESC] key
when the help object is active will close it.

Configure [F7]
Opens the configuration file for editing. When this object is closed, the
configuration will be immediately updated. If the "cfg.txt" file is opened
with the file browser and then closed, the configuration will not be
immediately updated.



Configuration File ("cfg.txt") Settings

Notes:
A '#' after the '=' indicates a number.
A '$' after the '=' indicates a string.
Spaces should not be used around the '='.
Each setting must consist of a single line.
True is '1' and false is '0'.

TabSize=#
# indicates the width of tabs, which must be at least 2.

ConvertTabsToSpacesOnLoad=#
If # is true, all tabs are converted to spaces every time a text file is
opened.

ConvertLeadingSpacesToTabsOnSave=#
If # is true, all leading spaces are converted to tabs every time a text file
is saved.

VisibleTabs=#
If # is true, tabs are highlighted.

TabKeyOutputsSpaces=#
If # is true, each time the tab key is pressed, spaces are used instead.

RunCommand1=$
RunCommand2=$
RunCommand3=$
RunCommand4=$
Up to four commands can be defined by these strings. When the corresponding
key [Alt+1], [Alt+2], [Alt+3], or [Alt+4] is pressed, the string is executed.
Each parameter should be surrounded by double-quotes and separated by spaces.
The application directory (ending with a slash) can be passed to the command
string by specifying the %1% tag in the string. If an appropriate file is
currently open (see below) its path can be passed to the command string by
specifying the %2ext% tag in the configuration, where "ext" is an optional
replacement file extension.
Example:
RunCommand1="%1%inform\win\infrmw32.exe" "+include_path=%1%inflib" "+temporary_path=%1%temp" "%2%" "%2z5%"

RunExtensions1=$
RunExtensions2=$
RunExtensions3=$
RunExtensions4=$
These correspond to the above commands. Each string consists of a list of
extensions separated by commas which tell the command interpreter what types
of files to pass to the %2ext% tag described above. The first open file which
has one of these extensions is passed to the command, with priority placed
upon the currently active object.
Example:
RunExtensions1=inf,i

ShowRunCommand1=#
ShowRunCommand2=#
ShowRunCommand3=#
ShowRunCommand4=#
These correspond to the above commands. If true, the command is run in a
window in front of the editor window. If false, the command is run in a
minimized window. These only apply to the Windows version.

RunCommandMenu1=$
RunCommandMenu2=$
RunCommandMenu3=$
RunCommandMenu4=$
These correspond to the above commands, and specify the text displayed in the
main menu.

SaveAllBeforeRunCommand=#
If true, all saveable objects are saved before running any command.

ErrorOutputType=$
$ is a three character code that determines the method of interpreting errors
that appear in the output and error objects after a command is executed. The
first character must be either 'o' for output, or 'e' for error. The next two
characters mark the end of the filename and the line number, respectively, in
the error string.
Example:
o()
works with default Inform and TADS error messages.

IndentSize=#
# is the size of indents.

CommentType=#
If 0, Inform/Hugo style comments are used.
Example:
!This is a comment.
If 1, C++/TADS style comments are used.
Example:
//This is a comment.

SaveWorkspaceOnExit=#
If true, the current directory, paths to all open files, and corresponding
cursor line positions are saved when the editor is closed. The information is
stored in the "wrkspace.txt" file in the configuration directory.

RestoreWorkspaceOnStartup=#
If true, the current directory, paths to all open files, and corresponding
cursor line positions are restored when the editor is started if any saved
workspace exists.

MaintainIndentation=#
If true, lines are automatically indented by the same amount as the previous
line after pressing the [Enter] key.

DirExtensions=$
Specifies a list of comma-separated file extensions. Files not matching these
extensions are not listed in the file browser object directory.
Example:
DirExtensions=inf,txt

NewExtension=$
Files opened with the New menu option are given this extension.

WindowsFontName=$
WindowsFontPoint=#
Only in the Windows version. These specify the font and point size used in the
editor workspace. The font must be monospaced, and can be changed while the
editor is running.
Example:
WindowsFontName=Courier
WindowsFontPoint=10

IndentWithTabs=#
If true, indents are filled with tabs when appropriate.

DefaultLinebreak=$
Specifies the default linebreak type used when a loaded file has no
linebreaks. This usually happens when an empty text file is opened. $ can be
"unix", "pc", or "mac".

SaveLinebreak=$
Specifies the linebreak type used when saving an object to a file. $ can be
"auto", "unix", "pc", or "mac". When "auto" the existing linebreak type is
preserved.



Format of the Colors File ("colors.txt")

This text file consists of pairs of color names that define the colors used
for displaying various sections of the workspace. The top color of each pair
defines the background color of that section. The bottom color of each pair
defines the foreground (text) color of that section. There are sixteen
possible color names: black, blue, green, cyan, red, magenta, brown, grey,
dgrey, lblue, lgreen, lcyan, lred, lmagenta, yellow, white. Modifications to
the colors file take effect the next time the editor is started.



Format of the Dictionary Files ("dict1.txt", "dict2.txt")

The first dictionary file is the main dictionary and should not be modified.
The second dictionary file is the user dictionary, and contains words added
with the "Add" option. Each dictionary file must contain no empty lines, and
no trailing linebreaks. The file must also contain only Unix linebreaks,
although this restriction is not strictly necessary. Dictionary words do not
need to be sorted alphabetically, must not begin or end with spaces, and may
only contain lower case letters, upper case letters, and apostrophes.



This Program Comes With No Warranty

Any losses or damages resulting from use of this program are not the
responsibility of the author. No matter what software you use, keep backups of
all important data on separate, reliable media at all times.
