SAMRC(5)

NAME
samrc - configure samterm

SYNOPSIS
~/.samrc

DESCRIPTION
A samrc file in the user's home directory can be used to configure the downloaded portion of the sam(1) editor (that is, samterm.) This file, if it exists, is read at startup.

Each line begins with a configuration directive and some number of arguments. Lines whose first printing character is a “#” are considered comments and are ignored. The following configuration directives are supported:

bind
    Bind a key sequence to a command or a raw character. The forms are:

            bind M K command C A
            bind M K command C
            bind M K raw C

    Where M is a string describing a set of modifier keys ( see Modifier Keys below), K is the name of a keyboard symbol suitable for passing to XStringToKeysym(3), C is either a command name ( for command bindings; see Command Names below) or a literal or hexadecimal specification of a character, and A is an arbitrary string to use as an argument to a bound command.

    Note that keyboard symbol names are implementation-defined and often case-sensitive, and that not all commands will make use of arguments.

unbind
    Remove all bindings associated with a key sequence. The form is:

            unbind M K

    where M is a string describing a set of modifier keys and K is the name of a keyboard symbol, as for “bind” above. The key sequence may be subsequently rebound.

chord
    Bind a mouse chord to a command. The form is:

            chord S1 S2 C T

    where S1 is a string describing the initial state of the mouse buttons ( see Mouse Button States below), S2 is a string describing the following state of the mouse buttons, C is a command name, and T is a target ( see Targets below).

unchord
    Remove all bindings for a given mouse chord. The form is:

            unchord S1 S2

    where S1 and S2 are strings describing the initial and following mouse button states. The chord may be subsequently rebound.

foreground
    Names the color used to draw text. It is of the form:

            foreground C

    where C is a color name suitable for passing to XAllocNamedColor(3).

background
    Names the color used to draw the background of files being edited. It is of the form:

            background C

    where C is a colon-separated list of color names as for the foreground directive. If more than one color is specified, files will cycle through these background colors.

border
    Names the color used to draw file borders. It is of the form:

            border C

    where C is a color specification as for foreground.

font
    Specifies the font used to draw text. It is of the form:

            font F

    where F is an fc-match(1) compatible font pattern.

tabs
    Specifies the width of tab characters in multiples of the width of the '0' character. It is of the form:

            tabs N

    where N is an integer between 1 and 12.

expandtabs
    Determines if tabs should be automatically expanded into spaces. It is of the form:

            expandtabs B

    where B is the string “true” or “false.” If “true,” then tabs will be automatically expanded.

autoindent
    Determines whether a line following a non-empty indented line is automatically indented. It is of the form:

            autoindent B

    where B is the string “true” or “false.” If “true,” then a new line after a non-empty indented line is automatically indented.

snarfselection
    Indicates which X selection should be exchanged with samrc upon execution of the exchange command (either via the menu item or key binding.) The forms are:

            snarfselection primary
            snarfselection secondary
            snarfselection clipboard

followfocus
    Determines window focus mode. It is of the form:

            followfocus B

    where B is the string “true” or “false.” If “true,” then the window focus mode is set to follow the mouse pointer. In this mode typing is directed to the window currently underneath the mouse pointer.

  Defaults
The default keybindings and mouse chords are those documented in sam(1). The default foreground and border color is black, and the default background color is white. Tabs are not expanded by default, and tabstops are set at every eight characters. The default X selection is “primary ”. The default window focus mode is "Click to focus". Typing is directed to the window which was last clicked.

  Modifier Keys
The bind directive expects a string describing the state of modifier keys. This string consists of one or more of “*” meaning any set of modifiers, “a” meaning Alt (Mod1,) “c” meaning Control, or “s” meaning Shift.

For example, bind the "exchange" command to Control-Shift-E, the following directive could be used:

        bind CS e command exchange

  Command Names
The following names can be used for commands:
Name | Meaning | Default Binding
escape | Highlight recent text | Escape
scrolldown | Scroll down by page | PgDn, Down/Right
scrollup | Scroll up by page | PgUp, Up/Left
scrolldownline | Scroll down by line | None
scrollupline | Scroll up by line | None
jump | Jump to/from command window | Control-K
charright | Move dot one to the right | Control-D
charleft | Move dot one to the left | Control-S
lineup | Move dot up | Control-E
linedown | Move dot down | Control-X
delbol | Delete to BOL | Control-U
delword | Delete prev. word | Control-W
delbs | Delete prev. character | BackSpace
del | Delete next character | Delete
cut | Cut selection | Control-Y
snarf | Snarf selection | Control-C
paste | Paste snarf buffer | Control-V
exchange | Exchange snarf buffer | Control-Q
eol | Move to end of line | None
bol | Move to beginning of line | None
tab | Insert a tab | Tab
send | Append to command window | None
write | Write the current file to disk | None
look | Find next literal string | None
search | Find next regex | None

Additionally, the command name “none” means that the given binding should perform no action (not even insert a character,) and the command name “default” means that the given binding should perform whatever action was previously defined for it.

For the send command, the text to send is specified in the argument of the binding. For example, to bind Control-Z to undo the last 10 changes, the following line binding could be used:

        bind C z command send u10

Note that the “send” command is analagous to the “send” menu item: the argument text is simply appended to the text in the command window. Thus, one should exercise caution if partially-completed commands exist in the command window.

  Mouse Button States
Chords are described using two states: a beginning state and an end state. When the mouse buttons are in the beginning state and then switch to being in the end state, the chord is activated.

States are described using button numbers between 1 and 5, corresponding to the buttons on the mouse numbered from the left (though this is up to your windowing system and may vary.) For example, the string

        12

means “buttons 1 and 2 are pressed”. The special string “n” means “no buttons are pressed”. Thus to bind the cut command to the chord “hold button one, then click button two” the following configuration directive can be used:

        chord 1 12 cut current

  Targets
Mouse chords can send their commands to either the current file (i.e. the one receiving typed input) by specifying "current" as the target; or to the file under the mouse pointer by specifying "mouse" as the target.

  Ordering considerations
Commands are executed in the order they are present in the samrc file. Later commands will override earlier commands, meaning that in the case of duplicate binding or chord definitions, the last one wins.

Note that this means that bindings defined with the “any” modifier set should be defined earlier in the file than those binding the same key with modifiers, since otherwise the “any” binding will always win.

EXAMPLES
An example samrc file is provided in the sam source distribution as doc/samrc.

SEE ALSO
sam(1)