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 is allowed 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.

Arguments are as follows:

count: A signed integer, the word none, or the word all.
editrule: An editrule (described below).
helptext: nroff-style help enclosed in quotes (also described below).
string: An arbitrary string enclosed in quotes. Note that within quotes, \ escapes the next character as when using awk(1).

A typical backup softkey node definition resembles:

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 hash-mark character (#) 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-like editing language. This translated word list is then passed to the shell for execution.

For a simple translation, this list might resemble:

_		_		_
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[number1]&=string: concatenate and assign

if Statement

The if statement is similar to the full-block mode if statement in awk, and is structured as follows:

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

Where the else part is optional. If number is non-zero, the first block of edit statements is executed. Otherwise, if the second block of edit statements is present, it is executed.

Word Allocation Statements

Word allocation statements include the following:

insert(number, string);: Insert string as a new word in the word list immediately before word[number].
append(string);: Insert string as a new word in the word list immediately after the last word in the word list. Equivalent to insert(next, string);.
dash(string);: Append string 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.
delete(number);: Delete word[number] from the word list.

Helptext

Each softkey node can 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 manual entries. 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 vertical 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, then 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 they consist of nothing more than a quoted empty string.

EXAMPLES

For a custom cd command (see cd(1)):

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, refer to the file /usr/lib/keysh/C/softkeys.

AUTHOR

keysh was developed by HP and AT&T.

FILES

$HOME/.softkeys: user softkey definitions file
/usr/lib/keysh/$LANG/softkeys: standard softkey definitions file