softkeys(4)

NAME

softkeys − keysh softkey file format

BACKGROUND

keysh softkey information is stored in the form of a softkey node hierarchy. The top level of this hierarchy represents the softkey commands themselves; lower levels represent various command options and parameters.

The softkey labels form a window into this softkey node hierarchy through which the user can view and select eligible nodes. A node is eligible if it was:

• Enabled by default and has not been subsequently disabled by the selection of some sibling node, or

• Disabled by default, has not been subsequently disabled by the selection of some sibling node, but has been subsequently enabled by the selection of some sibling node.

When a softkey node is selected, it can enable or disable any of its siblings as appropriate. A new window into the softkey node hierarchy is then computed as follows:

• If the selected node was not a leaf node, its eligible children are displayed;

• Otherwise, if the node still has eligible siblings remaining, they are redisplayed;

• Otherwise, if the node’s parent still has eligible siblings remaining, they are redisplayed, and so on, moving up the node hierarchy.

This process of node display and selection continues until the user has entered a complete command.

At that point, keysh performs the editrules associated with each of the selected softkey nodes. These editrules create the HP-UX command that is fed to the shell for execution.

SOFTKEY FILE FORMAT

Each softkey file contains one or more softkey definitions, each of which is represented as a sub-hierarchy of softkey nodes.

There are two basic types of softkey nodes:

option "Options" show up on softkey labels and insert literal text into the command-line when selected. Examples are command and option names.

string "Strings" (or "parameters") show up on softkey labels but do not insert text into the command-line when selected; rather, they display a hint message. The user must then type the desired text into the command-line. Examples are file and user names.

Note that the keyword softkey can be used as a synonym for the keyword option.

The basic softkey node definition is composed of the following components:

{option|string} <softkey>

<attribute>
.
.
.
;

Where <softkey> is the softkey node name from which the command-line text and softkey label are derived. If necessary, a single plus sign (+) within <softkey> can be used to force hyphenation of the softkey label at a syllable boundary.

If a softkey node has an associated sub-menu, its trailing ; is replaced with a list of child nodes as follows:

{
<softkey node>
.
.
.
}

Each softkey node can have the following optional <attribute> fields:

disable <count> Selecting this node will disable <count> softkey nodes to the right of this one − default is 0.

enable <count> Selecting this softkey will enable <count> softkey nodes to the right of this one − default is 0.

{filter|command} This node is only active for filters or commands, respectively − default is either.

{motorola|precision} This node is only active when keysh is running on a motorola (MC680x0) or precision (PA-RISC) processor, respectively − default is either.

disabled This node starts out disabled and must be enabled to be used − default is to start out enabled.

automatic The command will be entered automatically when this node is selected.

editrule <editrule> The editrule for this node.

cleanuprule <editrule> An editrule to be executed after all other editrules associated with this softkey command − only one cleanuprule may be specified per softkey command.

hint <string> The one line hint for this node − only valid for "string" softkey nodes.

help <helptext> The help for this node (may be more than one line).

required <string> The one line error message to display if this node is not selected.

Where <count> may be a signed integer, the word none, or the word all, <editrule> is an editrule (described below), <helptext> is nroff-style help enclosed in quotes (also described below), and <string> is an arbitrary string enclosed in quotes. Note that within quotes, \ escapes the next character as when using awk(1).

The basic backup softkey node definition looks like:

backup softkey <softkey> [literal <literal>] ;

Where <literal> is the literal text string to program the terminal function key with (if different than <softkey>).

An unquoted pound-sign (#) in a softkey file delimits a comment to the end of the line.

Softkey Command Translation

To translate softkey commands into HP-UX commands, keysh executes the editrules associated with each softkey selected by the user. These editrules create a word list via an awk(1)-like editing language. This translated word list is then passed to the shell for execution.

For a simple translation, this list might look something like:

_		_		_
ls		−l		∗.c
	_		_
_		_		_
word[0]		word[1]		word[2]

Every time an editrule is invoked, the special constants last and next are defined to the index of the last word in the list ("2" in this example) and the would-be-next word in the list ("3" in this example), respectively. In addition, the constant argument is set equal to the user input for the softkey (e.g., ∗.c for the softkey corresponding to the file name in this example).

Note that keysh automatically casts numbers and strings back and forth as necessary to carry out editrules. Also, variables are cleared only before the first editrule associated with a softkey command. All assigned variables are available to subsequent editrules.

Editrules

An editrule is a list of edit statements enclosed in curly-braces (i.e., { and }).

An edit statement is:

• an expression followed by a ;,

• an "if" statement, or

• a word allocation statement.

Expressions

A simple expression can be any of:

<variable>	single letter from a to z
<number>	unsigned integer
<string>	enclosed in quotes
<char>	enclosed in quotes

last	see above
next	see above
argument	see above

motorola	boolean flag
precision	boolean flag
command	boolean flag
filter	boolean flag

word[<number>]	see above

Simple expressions can be combined with any of:

<string>[<number>]	single character substring
<string>[<number>,<number>]	multiple character substring
<number>+<number>	addition
<number>−<number>	subtraction
<number><number*>	multiplication
<number>/<number>	division
<number>%<number>	modulus
<string>&<string>	concatenation
−<number>	negation
<string>==<string>	equality
<string>!=<string>	inequality
<number>>=<number>	greater than or equal
<number><=<number>	less than or equal
<number>><number>	greater than
<number><<number>	less than
<number>&&<number>	logical and
<number>\|\|<number>	logical or
!<number>	logical not
(<string>)	grouping

The following functions are also supported and return the indicated results:

strlen(<string>)	number of characters in <string>
strchr(<string>, <char>)	index of first <char> in <string>, or -1
strrchr(<string>, <char>)	index of last <char> in <string>, or -1
trim(<string>)	<string> without leading/trailing blanks
hex(<number>)	<number> in hex with leading "0x"
octal(<number>)	<number> in octal with leading "0"

Assignments can be done with any of:

<variable>=<string>	simple assignment
<variable>+=<number>	add and assign
<variable>-=<number>	subtract and assign
<variable>=<number>*	multiply and assign
<variable>/=<number>	divide and assign
<variable>%=<number>	modulus and assign
<variable>&=<string>	concatenate and assign
word[<number>]=<string>	simple assignment
word[<number>]+=<number>	add and assign
word[<number>]-=<number>	subtract and assign
word[<number>*]=**<number>	multiply and assign
word[<number>]/=<number>	divide and assign
word[<number>]%=<number>	modulus and assign
word[<number>]&=<string>	concatenate and assign

If Statement

The "if" statement is like the full-block mode "if" statement in awk. It looks like:

if (<number>) {
<edit statement>
    .
    .
} else {
<edit statement>
    .
    .
}

Where the "else" part is optional. If <number> is non-zero, the first block of <edit statement>s is executed. Otherwise, if the second block of <edit statement>s is present, it is executed.

Word Allocation Statements

The "insert" statement looks like:

insert(<number>, <string>);

And causes <string> to be inserted as a new word in the word list immediately before word[<number>].

The "append" statement looks like:

append(<string>);

And causes <string> to be inserted as a new word in the word list immediately after the last word in the word list. It is equivalent to insert(next, <string>);.

The "dash" statement looks like:

dash(<string>);

And causes <string> to be appended to the last word in the word list if that word already begins with a dash. Otherwise, a dash is inserted as a new word in the word list immediately after the last word in the word list and <string> is appended to that.

The "delete" statement looks like:

delete(<number>);

And causes word[<number>] to be deleted from the word list.

Helptext

Each softkey node may have an associated helptext, to be displayed upon a user request for help. This helptext is formatted on the fly and presented to the user through the preferred pager.

The helptext format is an nroff-like language, supporting a subset of the man(5) macros used to write standard HP-UX man-pages. In particular, this subset includes:

.nf Begin no-fill mode. Display text as-is, preserving new-lines and spaces, until a .fi.

.fi Resume fill mode. Display text with words filled onto each output line, attempting to utilize 90% of the screen width. (This is the default mode.)

.br Force a break in the current output line. Display subsequent text on the next line.

.sp Force a break and then display a single blank line (a space).

.P Force a break, display a single blank line, and then begin a new paragraph with no indent.

.IP <tag> <indent>Force a break, display a single blank line, and then display the specified tag. Finally, begin a new indented paragraph with the specified indent.

.IL <tag> <indent>Begin a new indented line (similar to .IP except no blank line is displayed).

Note that these macros are recognized anywhere in the input helptext, not just at the beginning of a line. Also, all macro arguments must be present, even if nothing more than a quoted empty string.

EXAMPLES

For a custom cd(1) command,

softkey cd
editrule { append("cd"); }
{
softkey keysh-src disable all
editrule { append("~/keysh/src"); }
;
softkey keysh-test disable all
editrule { append("~/keysh/test"); }
;
softkey keysh-doc disable all
editrule { append("~/keysh/doc"); }
;
softkey demo disable all
editrule { append("~/demo"); }
;
softkey tmp disable all
editrule { append("/tmp"); }
;
string <dir> disable all
editrule { append(argument); }
required "Enter the name of the directory to move to."
;
}

For other examples, see the file /usr/keysh/C/softkeys.

AUTHOR

keysh was developed by HP and AT&T.

FILES

$HOME/.softkeys user softkey definitions file

/usr/keysh/$LANG/softkeys standard softkey definitions file

Museum

Related Articles