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.