6.30.2 Locating source code definitions

Many programming systems are organized as an integrated development environment (IDE) where the editor is the hub of the system, and allows building and running programs. If you want that, Gforth has it, too (see Emacs and Gforth).

However, several Forth systems have a different kind of IDE: The Forth command line is the hub of the environment; you can view the source from there in various ways, and call an editor if needed.

Gforth also implements such an IDE. It mostly follows the conventions of SwiftForth where they exist, but implements features beyond them.

An advantage of this approach is that it allows you to use your favourite editor: set the environment variable EDITOR to your favourite editor, and the editing commands will call that editor; Gforth invokes some GUI editors in the background (so you do not need to finish editing to continue with your Forth session), terminal editors in the foreground (default for editors not known to Gforth is foreground). If you have not set EDITOR, the default editor is vi.

locate ( "name" –  ) gforth-1.0

Show the source code of the word name, set the current location there, and then call fancy-after-l for navigating the displayed source.

fancy-after-l ( c-addr1 u1 lineno1 – c-addr2 u2 lineno2  ) gforth-internal

Wait for keyboard input. If any other key than one of those mentioned below is pressed (in particular, if ESC or newline is pressed), fancy-after-l terminates; you can then reenter the fancy-after-l mode with l.
cursor-up, Ctrl-p, or k: Show one more line at the top.
Cursor-down, ctrl-n, or j: Show one more line at the bottom.
Page-up or ctrl-u: Show half of the terminal height more lines at the top.
Page-down or ctrl-d: Show half of the terminal height more lines at the bottom.
Ctrl-b: Scroll up by a full terminal height of source code, with only one line of overlap.
Space: Scroll down by a full terminal height of source code, with only one line of overlap.
Cursor-right or l: Switch to the next where, browse or backtrace result.
Cursor-left or h: Switch to the previous where, browse or backtrace result.
Ctrl-l: Redisplay the currently shown source code.

xt-locate ( nt/xt –  ) gforth-1.0

Show the source code of the word xt, set the current location there, and then call fancy-after-l for navigating the displayed source.

The current location is set by a number of other words in addition to locate. Also, when an error happens while loading a file, the location of the error becomes the current location.

A number of words work with the current location:

l ( ) gforth-1.0

Display source code lines at the current location, then call fancy-after-l for navigating the displayed source.

n ( ) gforth-1.0

Display lines behind the current location, or behind the last n or b output (whichever was later).

b ( ) gforth-1.0

Display lines before the current location, or before the last n or b output (whichever was later).

g ( ) gforth-1.0

Enter the editor at the current location, or at the start of the last n or b output (whichever was later).

You can control how many lines l, n and b show by changing the values:

before-locate ( – u  ) gforth-1.0

number of lines shown before current location (default 3).

after-locate ( – u  ) gforth-1.0

number of lines shown after current location (default 12).

Finally, you can directly go to the source code of a word in the editor with

edit ( "name" –  ) gforth-1.0

Enter the editor at the location of "name"

You can see the definitions of similarly-named words with

browse ( "subname" –  ) gforth-1.0

Show all places where a word with a name that contains subname is defined (mwords-like, see Word Lists). You can then use ww, nw or bw (see Locating uses of a word) to inspect specific occurrences more closely.