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

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.