Quick Start

GRIEF’s local configuration may be viewed using the --config option.

$gr --config

Examples

• Windows profile.

PROGNAME=C:/Program Files (x86)/Grief/bin/gr.exe
MACHTYPE=Win32
GRPATH=C:/Program Files (x86)/Grief/macros;C:/Program Files (x86)/Grief/src;
GRHELP=C:/Program Files (x86)/Grief/help;
GRPROFILE=
GRLEVEL=1
GRFILE=newfile
GRFLAGS=-i60
GRBACKUP=
GRVERSIONS=
GRDICTIONARIES=
GRDICTIONARY=
GRTERM=win32

• Linux profile.

PROGNAME=/usr/local/bin/gr
MACHTYPE=UNIX
GRPATH=/usr/local/share/gr/macros:/usr/local/share/gr/src:
GRHELP=/usr/local/share/gr/help
GRPROFILE=
GRLEVEL=1
GRFILE=newfile
GRFLAGS=-i60
GRBACKUP=
GRVERSIONS=
GRDICTIONARIES=
GRDICTIONARY=
GRTERM=linux

Environment

The more significant configuration elements which are required for correct operation are:

Editing any file is a simple as running GRIEF against the file image.

gr m_ruler.c

starts the editor, loading the specified file.

The file can be reviewed by navigating using Movement commands.

At any time during the file session online Help is available, plus the <F10:key_map> macro shall present the current keyboard binding.

The file content may be directly manipulated using Text Editing commands, components can be relocated using Cut and Paste or translated Search and Replace.  Any unwanted edits maybe corrected using Undo and Redo commands.

Once complete the edit session is complete a number of options are available.

If you execute the Exit command after text has been entered in any of the open files, the prompt below is presented.

1 buffer has not been saved. Exit [ynw]?

You will be given a number of choices.

The main features of the screen are the window arena, command line and status area.

Window Arena

The window arena is the area bounded by single and double lines, or borders, that displays the file content.  If the file is a new image, this space shall be empty and the window is blank.

The top border of the window contains the file name associated with the visible buffer, plus an optional modification indicator.  On right and bottom borders scroll bars represent the vertical and horizontal cursor position within the buffer when the buffer length or maximum line width are larger then the window arena.

Command Line

The command line, positioned below the window area, is dual purpose, used to display both messages and to prompt for information.  The command line is also referred to as the Command Prompt when acting to request user input.

Status Area

The status area, also referred to as the echo line, displays information about the current active buffer and general editor status.

GRIEF allows the full customization of the text displayed in the status area.  This is done through the echo_line and set_echo_format primitives.

The following attributes are displayed by the echo line format.

[x] $ Line: ### Col: ### OV RE/PA hh:mm

Active Character

The first elements identify the character under the cursor.  Normal printable characters are enclosed within a set of square brackets, with non-printable characters represented by their hexadecimal value.  When the cursor is positioned past the end of the current line, EOL is displayed, and when past the end of file, EOF is displayed.

Virtual Character

The character value is followed by the virtual character status from one of the following otherwise blank if a normal character:

Buffer Coordinates

The next two elements identify the line (row) and column where the cursor is located.  Unless invoked with restore enabled, when GRIEF is started the cursor is located at top of the current buffer, being line one(1) and column one(1).

Cursor Mode

On systems which have means of controlling the cursor, the current insert/overstrike mode is represented by the cursor shape; when in overstrike mode a large/block cursor is used and in insert mode a small/underline cursor is utilised.

Otherwise on systems without cursor control a mode indicator shall be displayed, OV when overstrike is active otherwise blank when in insert mode.

Remember Status

When macro recording is active or paused, RE and PA respectively are displayed.

Time

Last element in the status area is the time, which is displayed in hours and minutes, with a colon as a separator using a 12 hour format.

Buffer navigation is available using a rich set of the cursor commands.

Cursor Movement

Scroll Locking

Scroll-locking is a facility for keeping the cursor in a fixed position inside a window, accessed via the <ScrollLock> key toggling alternately between enabled and disabled.

The behaviour of scroll-locking is dependent on the number of visible windows.

When a single window is active, the cursor is locked into position.  Upon movement the cursor shall retain the same screen location, instead the buffer content is panned within the window where possible.

If multiple windows are active, scroll-locking allows two windows to be scrolled together.  This feature permits two files to be compared with one another, without the user needing to switch between windows in order to check the two file views in sync.  When enabled the user shall be prompted to select which other window the current window shall be synced with.

Scroll-lock to other window [<^V>]

Use of <Alt-H> or command help invokes the GRIEF help interface.

Help System

Pressing <Alt-H> during a normal editing session the menu of help topics appears.

+-----------------------+
| Help Menu             |
| Keyboard Summary      |
| Keyboard Mapping      |
| Macro Primitives  =>  |
| Explain           =>  |
| Features          =>  |
| Programmer Utils  =>  |
| User Guide        =>  |
| Programmers Guide =>  |
| About                 |
+-----------------------+

• Use the Up and Down arrows to move to the desired topic.
• Press Enter to review sub-topics.

Repeat this process until the desired help screen appears.  Esc or Backspace returns to the previous item or exits the help system when positioned at the top level menu.

Within the help text of the selected topic.

• The Up and Down cursor keys navigate the topic text.
• The Left and Right cursor keys plus Tab move between the available linked topics.
• Enter follows the current selected link.
• F5 searches the content of the current topic.

A more specialised <explain> interface also exists, that attempts to locate the help specific to the stated topic or function.

F10:explain

Command Help

Using <Alt-H> whilst at the command prompt, context specific shall be retrieved resulting in help for the current command being displayed.

For example, <Alt-G> executes the GoTo line command.  Whilst at the line prompt:

Go to Line:

The use of <Alt-H> shall now display help specific to the GoTo line command.  Once displayed the standard help keys can be used to navigate the help content.

Inserting text is simple, just start typing; see self_insert.

Pressing any character key inserts character into the current position.  If current position is in out-of-text area, empty area is filled with space or tab characters depending on editor settings.

GRIEF is a modeless editor, compared to vi, and it’s successor Vim, which are modal editors.  Modeless meaning that text is entered directly into the buffer as typed and commands are generally not context specific, behaving the same most of the time.  Modal editing, on the other hand, means that the editor switches between the state of inserting text and taking commands.

Editing Modes

The normal editing environment is referred to as the editing mode, and all of GRIEF’s commands and editing capabilities are available from it.

There are two variations on the editing mode: insert mode and overstrike mode.  In insert mode, typed text is inserted at the cursor.  In overstrike, existing text is overwritten as you type.  The insert mode is reflected in state of the cursor plus its status shall be visible within the status area.

Deletion and relocation of text is possible using the scrap buffer, see Cut and Paste.

Edit Commands

If we want to copy a block of text from one part of a buffer (think of a buffer as a file) to another, or from one buffer to another, we use the scrap.  The scrap is a temporary storage area for text which has been cut or copied from a buffer and can then be inserted as many times as necessary to some other buffer.  Cutting text is different from deleting text.  Cutting text deletes the original text but saves it so it can be inserted elsewhere.  The deleted text is gone.

In order for a piece of text to be cut/copied and then pasted it must first be highlighted.  To highlight a region of text, the user first drops an anchor.  As the cursor is moved away from the anchor, the text between where the anchor was dropped and the current cursor position is highlighted, showing the text which can be cut or copied.

There are three types of regions, block, column and line.  Block and line type is used to cut/copy and paste whole lines.  A column type is used to cut/copy and paste columns of text.

Search and Replace Commands

Search Attributes

Several options are available that control search behaviour, see <search_options>.  Most options are both mapped to keys in addition to being accessible on the <options> menus (Ctrl-O).

Regular Expression

Regular expression matching indicates whether certain characters have special meaning when performing searches.  When regular expressions are disabled search patterns are treated as string literals otherwise patterns are interpreted against the current syntax mode.

Case Sensitivity

Case sensitivity controls whether alphabetic characters should be compared as equivalent if they only differ in their case, for example whether A should match both a and A.

Block Selection

Block searching controls the action to be taken when a search is requested and the current buffer has a highlighted section.

If this option is off then the search is performed on the entire buffer, ignored the marked region.

If this option is on then the search begins at the start of the marked region and continues until a match is found or the end of the region is reached.

Syntax mode

Regular expression syntax mode indicates which expression syntax patterns are interpreted as.

Naming Scrap Commands

Similar to the scrap buffer primitives copy, cut and paste, exists the ability to act upon a named scrape buffer.  A named scrap behaves the same as the normal scrap, yet allows the user to keep separate copies of data in these temporary buffers.

The named scrap commands shall prompt the user for the name of buffer to be used.  Using <Tab> at these prompts shall present a popup showing the currently defined scrap names, allowing for both buffer management and selection operations.

Text are be manipulated by searching and/or translating selected text by the use of Regular expression search patterns.

Search and Replace Commands

Search Expressions

Search patterns are expressed in terms of a Regular expression.  Regular expressions are special characters in search or translate strings that let you specify character patterns to match, instead of just sequences of literal characters.

Regular expression characters are similar to shell wild-cards, yet are far more powerful.  There are several supported expression syntaxes, with the original BRIEF syntax being the default; see re_syntax.

These are the BRIEF regular expressions.

Note: Under the BRIEF syntax mode the *, @, and + expressions will always match as few of the expression in question as possible; also known as non-greedy matching.  UNIX-style greedy matching modifiers are also available for macro use.

Within replacement text the following are allowed.

Regular Expression Examples

The Regular Expression Toggle command turns expressions on or off.

Case sensitivity for searches and translates can be turned on and off with the Case Sensitivity Toggle.  When case sensitivity is off, “grief” will match “GRIEF”, ; when case sensitivity is on, it will only match “grief”.

The undo command can be used to undo any commands in the current buffer.

The undo facility can be compared to an edit audit trail, which tracks all modifications to the buffer, including edits, marked regions and cursor movement.  Each buffer records changes within the scope of the current editor session independent of other buffers, with an infinite level of undo information for each buffer.

The undo command reverses recent changes in the buffer’s text, and the undo command always applies to the current buffer.  Commands can be undone sequentially all the way back to the point where the buffer was opened or created.  If you undo too much you can use redo to cancel the last undo.

Undo Commands

Command line mode is entered by typing <F10>; see execute_macro.  The prompt allows access to commands which are not assigned to specific keystrokes to be executed by typing <F10> and entering the full command name for example <explain>.

Once typed the echo line along the bottom of the console shows the “Command:” prompt.  The command line is case-sensitive and all commands generally need to be entered in lower case to be recognised.

Command:

The command prompt shall also become active when user input is required by an interactive command, for example Goto Line.

Go to Line:

The command line has full editing features.  The Left and Right cursor keys allows navigation within the prompt, permitting text to be inserted and deleted.  Whilst at the prompt context specific help is available using <Alt-H> display help related to the current command.

Command History

Up to the last sixteen responses are saved for each prompt displayed; single character responses are ignored and not saved.  Use the cursor Up and Down keys to cycle through the list of remembered responses.  The Esc, which cancels the command is not stored.

You can also recall the last response entered at any prompt using <Alt-L>.  This is useful when you find you entered the correct response to the wrong prompt.  Press <Esc> to cancel the first command, issue the new command, and press <Alt-L> to recall the last response.

Command Completion

Certain commands for example Edit File can take advantage of the file name completion feature.  Type the first letters of the name and press <Tab>.  If only one file in the directory matches, it is completed.  If more than one file is found, a selection dialog is displayed allowing selection of the desired file.

Command Line Commands

During any command line interaction the available key binding are the following.

Files are always accessed by loading them into a buffer.  GRIEF is able to keep multiple files in memory at once, which allows the user to move among them easily.  Once a user is in GRIEF they can call up as many files as they need to use by loading them into a buffer within GRIEF.  Pop-up menus are often used when moving among files.  How to choose options on the pop-up menu is self-evident.  To exit a pop-up menu use the <Esc> key

Buffer Manipulation Commands

GRIEF windows can be tiled and used to look at more than one file at the same time, or different parts of the same file at the same time.

By tiling, we mean the window can be split horizontally or vertically.  This can be done as many times as you like, i.e. you can split your window into as many sections as you like.  Different buffers (files) can be viewed in different sections of the tiled window, or even different parts of the same buffer.

Each section of the tiled window can be treated as an individual GRIEF session.  Any changes to a buffer made in one part of a tiled window are displayed in the other parts of the tiled window displaying the same part of the same buffer

Window Manipulation Commands

Tiled Windows

Tiled windows are created by splitting the current window in half either horizontally or vertically, by default using <F3>, providing two views of the current buffer.

On request the user is prompted and the current window is split based on the direction of the selected arrow key.  On completion the newly created window is made current, with the cursor located at the same coordinates as the parent window.

Select new side [<^v>]

To create a new window, press one of these arrow keys.

Once created tiled windows can be resized and/or deleted using similar commands.

The minimum size of a window with borders on is two(2) lines deep by fourteen(14) columns wide.  When a split or resize request would result in the lower bounds being violated the follow shall be echoed and the request ignored.

Window would be too small.

GRIEF supports a facility to save keystroke sequences in a macro file that can be used later to save time.  This ability allows repetitively executed commands to be recorded and replayed as a single command; referred to as a keyboard macro.

Keyboard macros are stored in memory, plus these may be saved to file and reloaded, permitting a user to develop a private collection of simple macros.  Keystroke macros are saved as normal ASCII text and can be edited just like any other file.  You can create any number of remembered sequences during an editing session.  However, only one sequence is saved at a time.

The associated commands are summarised below.

There are numerous additional features available, many are directly available via the Feature Menus <Alt-F> and/or general menu, these include.

$Id: quickstart.txt,v 1.6 2024/05/12 07:50:33 cvsuser Exp $