SwiftForth supports interactive development and testing of Windows applications that can deliver very fast performance, and full access to standard Windows features, DLLs, and other powerful software found in this environment.
This introductory section gives a general view of the design of the SwiftForth development environment. We recommend that you read this, even if you are already familiar with the Forth language.
If you are a Forth beginner, read Forth Programmer’s Handbook carefully, and consider ordering Forth Application Techniques, a tutorial textbook offered by FORTH, Inc. Review some of the demo applications supplied with your system in the directory SwiftForth\lib\samples. Find out what software is available by looking through the source code files supplied with SwiftForth.
On This Page
2.1 SwiftForth Programming
SwiftForth is a powerful and flexible system, supporting software development for virtually any Windows application. Although the internal principles of SwiftForth are simple, a necessary side-effect of its power is that it has a large number of commands and capabilities. To get the most benefit, allocate some time to become familiar with this system before you begin your project. This will pay off in your ability to get results quickly.
2.2 System Organization
SwiftForth, like most Forth development systems, is a single, integrated package that includes all the tools needed to develop applications. SwiftForth adds to the normal Forth toolkit special extensions for Windows programming. The complete package includes:
- Forth language compiler
- Assembler
- Host system interface functions
- Libraries
- Interactive development aids
SwiftForth complies with Standard Forth, including the Core wordset, most Core Extensions, and most optional wordsets. Details of these features are given in Section 4.8 and Appendix B.
SwiftForth has two main components: a pre-compiled kernel and a set of options you may configure to suit your needs. In addition to these, you may add your application functions. When your application is complete, you may use the turnkey utility, described in Section 4.1.2, to prepare an executable binary image that you may distribute as appropriate.
A purchased SwiftForth includes source for all extensions and most kernel functions, as this can be valuable documentation, including a cross-compiler that can be used to modify the kernel.
2.3 IDE Quick Tour
The SwiftForth Interactive Development Environment (IDE) presents a user interface that may be managed with toolbar buttons and pull-down menus, or directly from the command line. This section summarizes its principal features.
Figure 2. The SwiftForth command window
2.3.1 The Command Window
Your main interface with SwiftForth is through the command window, which is displayed when the system boots. In this window, you may type commands, which will be executed by SwiftForth.
All information displayed in the command window (including commands you type, and system responses or displays) is kept in a large buffer while the IDE is running; you may scroll through it, using the scroll bar or the PageUp and PageDown keys, to see previous parts of the session. You may also print or save the entire buffer, or a portion of it that you select using the mouse.
The toolbar at the top of the command window provides one-click access to several menu options described in the following sections.
The status bar at the bottom of the command window shows the stack depth and the actual values of the top several items, the current number base (the default is decimal), and the current insert/overwrite typing mode. Clicking on the Base and Insert/Overwrite areas will step through possible values.
In addition to the buffer containing the general history of the command window’s contents, SwiftForth remembers the last several commands you type, storing them in a circular queue. The up-arrow and down-arrow keys allow you to retrieve these command lines from the buffer. You may edit them by using the left-arrow and right-arrow keys and typing; the Insert key toggles between insert and overwrite mode (as does clicking on the mode area of the status bar, discussed above). Press Enter to execute the entire line, or press Esc to leave the line without executing it.
The command-line input processor provides smart command completion. For instance, if you had previously typed INCLUDE FOO, typing INC and pressing the Tab key will complete the phrase INCLUDE FOO for you. Successive presses of the Tab key toggle through entries in the circular command-line buffer.
Double-clicking any word in the command window will select it. The right mouse button presents a menu of operations you can apply to a selected word:
Locate displays the source for any word defined in your current scope by double-clicking the word. If the source is not present (e.g. you are running a turnkey but do not have the source files that generated it) or if the word you are trying to LOCATE was defined interactively in the command window, you will see the error message “Source file not available.” This feature is discussed further in Section 2.4.1.
Edit launches or switches to your linked editor (see Sections 2.3.5 and 2.4.1) positioned at the source for the word (if it’s available).
See disassembles the word, as described in Section 2.4.4.
Cross Ref generates a cross-reference for the word, as described in Section 2.4.3.
Execute executes the word, just as though you had typed it and pressed Enter.
Copy copies it to the clipboard.
Paste pastes whatever is currently in the clipboard at the current cursor position in the command window.
Copy and Paste (below the horizontal line in the menu) are a little bit different. The functions above the line require that you have selected a recognizable Forth word (or, in the case of Execute, an executable word or number). Copy does not depend on the selected text being a defined Forth word, and Paste will ignore any selected text.
The following table summarizes the special keyboard functions available in the command window:
Key | Action |
---|---|
PageUp / PageDown | Scroll through the history of the current session |
UpArrow / DownArrow | Retrieve commands you have typed |
LeftArrow / RightArrow | Move the cursor on the command line |
Insert | Toggle the insert/overwrite mode of typing |
Ctrl-C | Copy highlighted text from the command window |
Ctrl-V | Paste text to the command line |
Ctrl-Home | Show command history |
Ctrl-Shift-Del | Delete to the end of the command line |
Esc | Delete the entire command line |
Tab | Auto-complete from command history |
Ctrl-T | Transpose the two characters before the cursor |
The following sections describe the options available from the command window menu and toolbar. Where a letter in a menu item is underlined, the Alt key plus that letter is a keyboard equivalent. In each case, we list the menu item, equivalent commands (if any, in addition to the Alt versions), and a description.
2.3.2 File Menu
The File menu offers the selections described in Table 2.
Table 2: File menu options (continued)
Item Command Action
Include INCLUDE Interpret a file (load it and any files it loads). Displays a file-selection dialog box; INCLUDE processes the file filename.
Edit EDIT or
EDIT Launch a linked editor, allowing you to select a source file or word.
Print Print the command window.
In the print dialog, you may choose to print the entire contents or a selected portion.
Save Command Window Record the current contents of the command window in a text file.
Save Keyboard
History Record all the commands you’ve typed in this session in a text file.
Session Log Start recording all actions for this session in a text file.
Break Force the main console task in SwiftForth to abort; used for error recovery.
Exit bye Exit SwiftForth.
The Edit menu option opens a file for editing, using your linked editor (see Sections 2.3.5 and 2.4.1).
Both File > Include and File > Edit and their corresponding toolbar buttons display a “Browse” dialog box with which you can find your file. Both reset SwiftForth’s path to the one for the file you select. However, INCLUDE typed from the keyboard does not change SwiftForth’s path.
Save Command Window, Save Keyboard History, and Session Log are discussed further in Section 2.4.8.
2.3.3 Edit Menu
Most editing in SwiftForth is done with your associated editor (see Section 2.3.5 and Section 2.4). However, you can copy text—from a file in another window or from elsewhere in the command window—and paste it into the command window, which will have the same effect as typing it. You may also select text for typing, saving, or copying into another window. Edit menu options are summarized in Table 3. (Cut and Delete are not available in the command window, since the purpose of the command window is to maintain a record of your actions during this programming session.)
Table 3: Edit menu options
Item Keystroke Action
Copy Ctrl-C Copy selected text to your clipboard.
Paste Ctrl-V Paste the current clipboard contents on a new
command line and interpret its contents.
Select all Selects the entire contents of the command window.
Wipe all Clear the entire command window.
Toolbar buttons are available for Copy and Paste.
2.3.4 View Menu
The View menu provides alternate views of the command window. If the feature is active, a checkmark appears next to it on the menu. See Table 4.
Table 4: View menu options
Item Action
Status line When checked, displays the status line at the bottom of the debug window.
Toolbar When checked, displays the toolbar at the top of the debug window.
2.3.5 Options Menu
The Options menu provides more ways to customize SwiftForth. Options menu selections are summarized in Table 5.
Table 5: Options menu selections
Item Action
Font Select a font for the command window.
Only fixed-width (i.e., non-proportional) fonts are listed.
Editor Select and set parameters for your editor.
Preferences Set text and background colors for normal and highlighted displays and other options.
Warnings Enable/disable various system warnings, and establish how they and error messages will be displayed.
Include Monitoring Sets options for diagnostic features to be performed during file INCLUDE operations. See Section 3.3 for details.
FPMath Options If floating-point math support has been loaded (Tools > Optional Packages > Generic Options > FPMath), customize related features.
To use an editor other than Notepad, which is the default when SwiftForth is shipped, use the Options > Select Editor menu item, and type your editor’s pathname into the box or click the browse button to search for it. After you have provided the pathname, the User Defined radio button should be highlighted.
Figure 6. Select Editor dialog
Next, you must specify how SwiftForth is to pass line-number and filename parameters to your editor. The specification format is:
%l ” %f”
Note that the file-selection string and %f require quotation marks around them, since the filename may contain spaces.
When SwiftForth calls the editor, it will provide the line number at the place in this string that has a %l (lower-case L), and will provide the filename at the place that has a %f. Sample parameter strings for some editors are shown in Table 6. SwiftForth already knows the appropriate strings for these and other popular editors; if the one you’ve selected is among them, it will automatically enter its strings. Otherwise, you may fill them in.
Table 6: Examples of editor parameter sequences
Editor name Parameter string
CodeWright “%f” -g%l
E -n%l “%f”
ED4W -1 -n -l %l “%f”
EMACS +%l “%f”
MultiEdit “%f” /L%l
TextPad -am -q “%f”(%l,0)
TSE -n%l “%f”
Ultra Edit “%f” -l %l
When your editor’s pathname and parameter string are correct, click Done. This information will be saved when you exit SwiftForth.
SwiftForth’s Options > Preferences dialog (or its equivalent Toolbar button) lets you specify a number of configuration items, shown in Figure 7.
Figure 7. Preferences dialog
The Colors section controls the color scheme for the command window.
The checkbox “Use coloring for WORDS” affects the command WORDS (described in Section 2.4.2). If this box is checked, typing WORDS in the command window will produce a color-coded display in the command window; otherwise, no coloring is applied.
The “Reset” button will restore all options to the system defaults.
The “Flat” and “Large” toolbar buttons affect the appearance of the toolbar, if it is displayed.
“Pause while scrolling” sets the scrolling mode of words that generate lots of output (DUMP, SEE, WH, WORDS etc.). When this option is enabled, the output will pause with the prompt “Press space for more…” at the bottom of each screen full of output. When this option is disabled, output just scrolls with no pause.
The Options > Warnings dialog (Figure 8) provides configuration settings that determine whether, and where, error messages and system warnings will appear.
Even if warnings are disabled, error messages will always be displayed. See Section 4.7 (”Exceptions and Error Handling”).
Because SwiftForth is normally case insensitive, the box labeled “Warn for case ambiguity” is normally unchecked. If it is checked, it will warn of name conflicts based on case alone.
Figure 8. System warning configuration dialog
Options > Include monitoring configures diagnostics that can be used when you INCLUDE a source file. These are discussed in detail in Section 3.3.
Options > FPMath Options displays a dialog box that provides several ways to customize floating-point options. This menu selection is only available if floating-point math support has been loaded (Tools > Optional Packages > System Options > FPMath). See Section Section 12: for details.
SwiftForth is built using a kernel plus a set of additional features. These are incorporated into the Sf.exe program you usually boot. If your version of SwiftForth includes system source code, you can customize it by adding or removing features.
References
WORDS command, Section 2.4.2
INCLUDE, Section 3.1
Floating-point math library, Section Section 12:
2.3.6 Tools Menu
This menu provides tools that may be helpful in the development process.
Table 7: Tools menu options
Item Command Action
Break Force the main console task in SwiftForth to abort; used for error recovery.
History Open command history window, and start recording
Run RUN Run an auxiliary program, such as a checkout procedure for a version-control program.
Optional Packages Select from among many optional libraries.
The Options > Optional Packages sub-menu offers several choices; each displays a dialog box from which you can select the items you want. There are several major options, and a number of minor ones, including the sample programs described in Section 1.4.2.
The options offered by SwiftForth are organized into four groups, shown in Table 8.
Table 8: SwiftForth Optional Packages
Group Description
Generic Options Extensions to SwiftForth that are not platform-dependent, such as floating point math, extensions to the object package, and various math functions.
Win32 Options Windows-dependent extensions, such as various forms of dialog boxes and other kinds of controls, a console debugging feature, a simple DDE client, some graphics tools, etc.
Generic Samples Some examples of floating point and other non-Windows coding tricks.
Win32 Samples A rich collection of samples of code that exploit various Windows features, from TCP/IP communication to graphics, including the popular Sokoban and Tetris games.
Figure 9. Optional packages selection
When you select a group, you will be presented a dialog box listing the packages available in that group, such as the one in Figure 10. Use your mouse or arrow key to move up and down in the list. As you select each item, you will be shown a brief description of it.
Figure 10. Load options dialog
The major items listed under Win32 Options are described in Table 9.
Table 9: Some representative “Win32 Options”
Filename Description
BLKEDIT polyFORTH block editor (includes PARTSMAP).
DDECLIENT API for DDE client services.
FPMATH Hardware (Intel FPU) floating-point math library (Section Section 12:).
PARTSMAP Block support (ANS Forth Blocks wordset plus extensions).
PFASSEMBLER polyFORTH-compatible assembler (see polyFORTH
documentation for details).
PROTECTION Re-defines most common memory access words to ensure action within legally accessible memory.
RANDOM Parametric multiplicative linear congruential random-
number generator.
RATIONALAPPX Rational approximations.
In addition to these options, SwiftForth also includes the Forth Scientific Library, a collection of mathematical algorithms implemented in ANS Forth by a group of independent programmers. These routines may be found in the SwiftForth\Unsupported\FSLib directory, along with Info.txt which describes the library and its contributors. FORTH, Inc. provides this library as a service to SwiftForth programmers but, since we did not develop it, we cannot support it or assume any responsibility for it.
To save a SwiftForth system configured to your taste, load the options of your choice, then type:
PROGRAM
to record a turnkey version of the system as filename.exe.
This feature is not available in the SwiftForth evaluation version.
References
Command history window, Section 2.4.8
Using PROGRAM to make a turnkey image, Section 4.1.2
DDE Client Support, Section 8.3
2.3.7 Help Menu
The Help menu provides access to documentation for your SwiftForth system.
2.4 Interactive Programming Aids
This section describes the specific features of SwiftForth that aid development. These tools will typically be used from the keyboard in the command window.
2.4.1 Interacting With Program Source
The command:
LOCATE
is equivalent to selecting a word in the command window (as discussed in Section 2.3.1) and selecting the Locate right mouse menu option. If name is defined in the current search order, this will display several lines from the source file from which name was compiled, with name highlighted. The amount of text actually displayed depends on how large your command window is just now; the display will use two-thirds of the available lines.
LOCATE will work for all code compiled from available source files; source is not available for:
code typed directly into the SwiftForth command window
source code copied from a file and pasted into the command window
code from files not supplied with the version of SwiftForth you are using
words in the SwiftForth metacompiler
LOCATE may also fail if the source file has been altered since the last time it was compiled, since each compiled definition contains a pointer to the position in the file that produced it.
For example, to view the source for the word DUMP:
LOCATE DUMP
The LOCATE command opens the correct source file, and displays the source:
C:\ForthInc\SwiftForth\src\ide\tools.f
49: -? : DUMP ( addr u — )
50: BASE @ >R HEX /SCROLL
51: BEGIN ( a n) 2DUP 16 MIN DUMPLINE
52: 16 /STRING DUP 0 <= UNTIL 2DROP 53: R> BASE ! ;
54:
After you have displayed source for a word in the command window, typing N (Next) or B (Back) will display adjacent portions of that source file.
The actual amount of text displayed will depend on the size of your command window. SwiftForth calculates the number of lines to display based on the current debug window size
If you select a word in the command window, the popup menu generated by a right-click will offer (among others) the option Edit. Selecting that command will launch your linked editor (or switch to it if it is already open) with the cursor positioned on the source line containing the word. This feature lets you immediately edit the source, if you wish, and examine the rest of the file. (Use of the Options menu to link to an editor other than the default Notepad is described in Section 2.3.5.)
If the compiler encounters an error and aborts, you may directly view the file and line at which the error occurred by typing L. This is particularly convenient if you have a linked editor (see Section 2.3.5), because you can immediately repair the error and recompile. If you don’t have a suitable editor, SwiftForth will display the source path and line number in the command window, and you will have to manually switch to your editor to fix the problem.
Glossary
- LOCATE
- ( — )
Display the source from which name was compiled, with the source path and definition line number, in the SwiftForth command window. name must be in the current scope. Equivalent to double-clicking on name and selecting the Locate option from the menu generated by a right-click. The number of lines displayed depends on the current size of the SwiftForth command window.
- N
- ( — )
Display the Next range of lines following a LOCATE display.
- B
- ( — )
Display the previous (Back) range of lines following a LOCATE display.
- L
- ( — )
Following a compiler error, display the line of source at which the error occurred, along with the source path and line number, in the SwiftForth command window.
- G
- ( — )
Following a compiler error, opens the linked editor with the cursor positioned on the line where the error occurred.
- EDIT <name>
- ( — )
Launches or switches to a linked editor, passing it appropriate commands to open the file in which name is defined, positioned at its definition. If name cannot be found in the dictionary, EDIT will abort with an error message.
2.4.2 Listing Defined Words
The command WORDS displays a list of all defined words in the current search order (i.e., currently accessible in the dictionary). If the option “Use coloring for WORDS” is selected in the Options > Preferences dialog box (Section 2.3.5), typing WORDS will display the words color-coded to indicate their category as shown in Table 10, and you can double-click any such displayed word to select it and LOCATE its source or any of the other “right mouse button” actions described on page 22.
Table 10: Color-coding in WORDS
Color Category
Black Default (no recognized category)
Blue Inline words (i.e., words expanded to inline code)
Red CONSTANTs
Green VARIABLEs
Cyan Menu items
Magenta Immediate words
Dark yellow User variables
Dark blue VALUEs
Dark red Wordlists
Dark green WinProcs
Dark cyan Windows functions
Dark magenta Switches
You may see words in a particular vocabulary by specifying a vocabulary before WORDS. For example:
FORTH WORDS
will show only those in the FORTH vocabulary. Alternatively, you may specify ALL WORDS to get all defined words in all current vocabularies. You may search for words with a particular character sequence in their names by following WORDS with the search string. For example, if you type:
ALL WORDS M*
you will get this response:
M/ M UM*
3 words found. ok
In other words, these three words contained the sequence M* in their names.
References
Search orders, wordlists, and vocabularies, Forth Programmer’s Handbook
Wordlists in SwiftForth, Section 5.5.2
2.4.3 Cross-references
SwiftForth provides tools to enable you to find all references to a word, and also to identify words that are never called in the currently compiled program.
To find all the places a word is used, you may type:
WHERE
It displays the first line of the definition of name, followed by each line of source code that contains name in the currently compiled program.
If the same name has been redefined, WHERE gives the references for each definition separately. The shortcut:
WH
does the same thing. This command is not the same as a source search — it is based on the code you are running on right now. This means you will be spared any instances of name in files you aren’t using. However, it’s also different from a normal dictionary search: it searches all wordlists, regardless of whether they are in the current search order. This is to reveal any definitions or usages of the word that may be currently hidden and, therefore, the source of subtle bugs.
Here’s an example of a display produced by WH (used on a word in the sample program scribble.f):
WH POINT#
WORDLIST: FORTH
C:\ForthInc\SwiftForth\lib\samples\win32\scribble.f
125 13| 0 VALUE POINT#
125 24| POINT# 1 > IF
125 27| POINT# 1- 0 DO
125 28| POINT# 1 DO
125 38| POINT# #POINTS < IF
125 39| LPARAM POINT# CELLS POINTS + !
125 40| 1 +TO POINT#
125 87| SCRIBBLING ?EXIT 0 TO POINT#
The first line shows the wordlist name of the wordset in which the word was found. The next lines show where it was defined, and the lines following show all references to it. The numbers to the left of the vertical bar are line numbers in the file; if you click on one of these, you will select it, making it available for the “right mouse button” actions described on page 22.
Conversely, you may be interested in identifying words that have never been used, perhaps to prune some of them from your program. To do this, type UNCALLED. This will list all such definitions, as well as WINPROCs in open DLLs. As with the WHERE display, you may double-click the line numbers to select that source for further examination. Note that the fact that a word appears in this list doesn’t necessarily mean you want to get rid of it.
Glossary
WHERE , WH ( — )
Display a cross-reference showing the definition of name and each line of source in which name is used in the currently compiled program. WH and WHERE are synonyms.
UNCALLED ( — )
List all words that have never been called in a colon definition.
References
Wordlists, Forth Programmer’s Handbook
Wordlists and vocabularies in SwiftForth, Section 5.5.2
2.4.4 Disassembler
The disassembler is used to reconstruct readable source code from compiled definitions. This is useful as a cross-check, whenever a new definition fails to work as expected, and also shows the results of SwiftForth’s code optimizer.
The single command SEE name disassembles the code generated for name. Since SwiftForth compiles actual machine code, it is unable to reconstruct a high-level definition. You may use LOCATE to display the source.
For example, the definition of TIMER (see Section 4.4.2) is:
: TIMER ( ms — )
COUNTER SWAP – U. ;
It disassembles as follows:
SEE TIMER
45A353 454883 ( COUNTER ) CALL E82BA5FFFF
45A358 0 [EBP] EBX SUB 2B5D00
45A35B 4 # EBP ADD 83C504
45A35E 407BC3 ( U. ) JMP E960D8FAFF ok
The leftmost column shows the memory location being disassembled; the rightmost column shows the actual instruction.
An alternative is to disassemble or decompile from a specific address:
DASM
This is useful for disassembling code from an arbitrary address. The address must be an absolute address such as may be returned by a LABEL definition, a data structure, or obtained from an exception (see Section 4.7).
Glossary
SEE ( — )
Disassemble name.
DASM ( addr — )
Disassemble code starting at addr.
References
Using LOCATE to display source, Section 2.4.1
CODE and LABEL, Section 6.2
2.4.5 Viewing Regions of Memory
Regions of memory may be dumped by using the commands DUMP, IDUMP, UDUMP, and HDUMP. All take as arguments a memory address and length in bytes; they differ in how they display the memory:
DUMP displays successive bytes in hex, with an ASCII representation at the end of each line.
IDUMP displays successive single-cell signed integers in the current number base.
UDUMP displays single-cell unsigned numbers in the current number base.
HDUMP displays unsigned cells in hex.
Data objects defined with VARIABLE, CREATE, or defining words built using CREATE will return suitable memory addresses. If you get an address using ‘ and wish to see its parameter field or data area, you may convert the address returned by ‘ to a suitable address by using >BODY.
Example 1: Dumping a string
CREATE MY-STRING CHAR A C, CHAR B C, CHAR C C,
MY-STRING 3 DUMP
displays:
45F860 41 42 43 ABC
Example 2: Dumping a 2CONSTANT
5000 500 2CONSTANT FIVES
‘ FIVES >BODY 8 IDUMP
displays:
0045F87C: 500 5000 ok
Glossary
DUMP ( addr u — )
Displays u bytes of hex characters, starting at addr, in the current section, which may be either code or data. An attempt at ASCII representation of the same space is shown on the right. Addresses and data are displayed in hex.
IDUMP ( addr u — )
Displays u bytes, starting at addr, as 32-bit signed integers in the current base.
UDUMP ( addr u — )
Displays u bytes, starting at addr, as 32-bit unsigned numbers in the current base.
HDUMP ( addr u — )
Displays u bytes, starting at addr, as unsigned hex numbers.
References
Number bases, Section 4.3
Dictionary entry format and parameter fields, Section 5.5
2.4.6 Single-Step Debugger
SwiftForth’s simple single-step debugger allows you to step through source compiled from a file. The sample program sstest.f can be loaded with the phrase:
REQUIRES SSTEST
When the source has been compiled from the file sstest.f, type the following to invoke the single-step interface:
4 DEBUG 5X
At each breakpoint between Forth words, the current data stack is displayed along with a prompt to select the next action:
Nest Execute the next word, nesting if it is a call.
Step Execute the next word, with no nesting.
Return Execute to the end of the current definition without stopping.
Finish Finish executing the DEBUG word without stopping.
To load the single-step debug support without the 5X example above:
REQUIRES SINGLESTEP
2.4.7 Console Debugging Tool
The console debugging tool lets you get debugging information that is not available interactively—such as traces during execution of dialog box code or Windows callbacks—as the console is completely independent of the Windows GUI interface.
An example use is in the sample program bugsample.f, reproduced below:
REQUIRES CONSOLEBUG \ Include console debug routines
1 TO BUGME \ 0 means debug not active
: TEST
[BUG CR .” TESTING” .S BUG] \ Anything output-oriented
[BUG KEY DROP BUG] \ KEY for PAUSE also available
DUP * DROP ;
: TRY
10 0 DO
I TEST
LOOP ;
Any words between [BUG and BUG] will be executed if BUGME is not zero.
A common use of this feature is to display the parameters on each entry to a callback being debugged.
2.4.8 Managing the Command Window
The command window is implemented internally as a circular buffer; a long session may “wrap” this buffer, so early commands may be lost. Three of the File menu options allow you to record the events of a development session in various ways:
Save Command Window records a snapshot of the present contents of the command window in a text file. This is useful if, for example, you have just encountered a strange behavior you would like to record for later analysis.
Save Keyboard History records into a text file only the commands you’ve typed. Such a file may be edited, if you like, using your text editor. You can replay these commands by including the file. This is useful for developing scripts or for reproducing a bug.
Session Log opens a file and starts recording everything that happens thereafter in the session, until you turn it off by re-selecting this menu item. While it is active, its menu item displays a check mark.
You may display a window containing the keyboard history by selecting Options > History or the Toolbar button. You can edit the contents of this window, using it as a scratch area, and you may copy and paste selections from this window into the command window.
References
File menu, Section 2.3.2