							1999-05-31
							Emil Brink

		Argument to Built-In Commands

1. INTRODUCTION
This little text outlines gentoo's support for argument to its
built-in commands. This support was first introduced in release
0.11.6, but is likely to grow as more commands are added and/or
old commands extended to support it.


2. WHAT'S NEW
In releases prior to 0.11.6, gentoo's built-in commands either did
not accept any kind of information from the user, or popped up some
sort of interactive GUI to get the required parameters. Good examples
of these two "types" of built-ins are the DirEnter and SelectRE
commands; the former always figured out for itself what it should
do, while the latter always presented a dialog for parameters.
	The addition of arguments to built-in commands changes this;
now you can control commands directly from the invocation string. To
take SelectRE as an example, you could now specify a command to toggle
the selection state of all currently non-selected, non-directory
items containing the word "foo" in their name, by giving a command
such as:

    "SelectRE set=unselected action=toggle glob=true *foo*"

This will cause the SelectRE command to immediately perform the
requested matching and selection action; there will be no dialog
window.


3. ARGUMENT SYNTAX
The command argument system in gentoo is somewhat different from
what is common in e.g. shells. There are two different kinds of
arguments that can occur in a command line: keywords and non-
keywords (also called "barewords").
	Keywords use the keyword=value syntax. A bareword, on the
other hand, is a string that does not contain an equals ("=") sign.
	Commands generally take zero or one bareword argument as
their main input on what to do, and then zero or more optional
keyword arguments to further control the action. The SelectRE
command shown above is a good example; it takes as a bareword arg
the regular expression to match against, and up to seven different
keyword arguments to modify the way the selection is done.
	When compared to the syntax used in common command line
interpreters like bash, this seems to be an extremely wordy and
inefficient syntax. This might be true, but remember that commands
in gentoo are generally not issued interactively, rather they are
written once when configuring gentoo, and then executed by the click
of a button or press of a key. Therefore, IMO, it is not as import-
ant to optimize the command lines for speed of entry.

3.1 OVERALL KEYWORD SYNTAX
The "keyword" part should be a sequence of non-blank characters.
Typically, it will consist of nothing but alphabetical symbols
(letters). Keywords are case insensitive. Keyword VALUES are typically
NOT case insensitive!
	The "value" part will typically be an arbitrary string.
Separating the two parts is an equals sign (=). There must not be
any whitespace on either side of the equals, since that would separate
the argument into multiple arguments.

3.2 KEYWORD VALUE SYNTAX
Currently, there are three (rather lazily defined) types of value
arguments; strings, booleans, and enumerations.

3.2.1 Strings
A string is the simplest form of value: it has no special structure
known to the command argument system. It's just a string of text.

3.2.2 Booleans
Booleans are to be interpreted as either TRUE or FALSE. To make a
boolean argument evaluate to TRUE for the command, specify one of
"yes", "true", "on" and "1" as the value part of the argument. In
fact, "" (the empty string) works just as well. Any other string
(like "no", "false", "foo", and "I_do_not_think_so_pal") will render
a value of FALSE to the command.

3.2.3 Enumerations
Enumerations are arguments whose value part should be one of a small
set of predefined strings. The "set" and "action" arguments shown in
the SelectRE example above are enumeration arguments. Below, the
legal enumerations for each command will be listed. Please note that
enumerations are case-insensitive as well.


4. COMMAND ARGUMENTS
This section describes the arguments understood by each builtin
command in gentoo. If a command is not listed, that means it does
not take any arguments. Passing arguments to a command that doesn't
take any, or passing the wrong arguments, will (in most cases) have
no effect.
	For each keyword argument below, its type is listed.
Enumerations will have the valid set of strings listed. In most cases,
these enumerations will have the exact same wording as some GUI
controls for the same command, and will therefore (hopefully) be
more or less self-explanatory.
	Bareword arguments are shown as having type "bareN", where
N is the index on the command line of the word (counting only the
barewords). If N is missing, the command takes only one bareword
argument. Keywords that appear in parentheses below are actually
barewords (they all have "bare" in the Type column) !

DirEnter
Keyword 	Type	Description
dir		string	The path you want to enter. If relative
			(not starting with a '/'), it will be
			relative to the contents of the current
			pane. If not specified, DirEnter will
			check the selection as usual.
(dir)		bare	You can also specify the path as a bare
			word. This will not work if the path
			contains the '=' symbol, though.

DpFocus
Keyword		Type	Description
center		bool	Causes the currently focused row, if any,
			to be vertically centered in the pane.
select		bool	If TRUE, the row that is current BEFORE
			any movement of the focus bar has its
			selection status toggled.
(command)	bare	Use this bareword to control what the
			focus bar should do. There are several
			different words available:
			none	Hide the focus bar.
			same	Leave the bar alone. This is the
				default.
			prev	Move bar up one row.
			next	Move bar down one row.
			first	Move bar to first row in pane.
			last	Move bar to last row in pane.
		      activate	Activate focused row; works like
				a double-click of it would.


FileAction
Keyword		Type	Description
action		string	The FileAction is used to operate upon files
			in a pane. It runs commands specified in the
			each file's style, as action properties.
			The argument is the name of the action to
			run. If no argument is given, the default
			action ("Default") is executed. Note that
			the property name is case sensitive: you must
			use the exact same casing as when you defined
			the property.
			  This command replaces the older FileDefault,
			FileView, FileEdit etc. commands.

SelectRE
Keyword		Type	Description
set		enum	Determine the set of rows to do the
			selection in, based on the rows' current
			selection status. Valid values are "all
			rows", "selected", and "unselected".
type		enum	Further affect the set of affected rows,
			this time based on the row's file system
			type. Valid values are "all types",
			"directories only", and "non-directories
			only".
action		enum	Controls what is done with rows that match
			the expression. Should be one of "select",
			"unselect" and "toggle".
glob		bool	If TRUE, the regular expression will be
			interpreted as a shell glob pattern. If
			not, it will be taken as a true RE.
invert		bool	If TRUE, invert the sense of the matching.
full		bool	If TRUE, require the expression to match
			full text of a row's name. If FALSE,
			a partial match (e.g. "a" matches "abc")
			will do.
nocase		bool	When TRUE, the regular expression matcher
			will ignore differences in case between the
			expression and the filenames.
(re)		bare	The actual regular expression to match. If
			this word is not present, any keyword args
			will be ignored, and the dialog will appear.

Arguments to the SelectRE command will retain their values across
invocations, and will also appear as defaults in the GUI the
next time it appears.


ViewText
Keyword		Type	Description
mode		enum	Controls how ViewText will view the contents of
			a given file. If absent or set to "auto", it will
			inspect the beginning of the file; if it looks
			like plain ASCII text, it will be viewed as such.
			If not, or if mode is set to "hex", it will be
			viewed as hexadecimal data. You can also set the
			mode to "text" to force ASCII viewing.


Quit
Argument	Type	Description
dialog		bool	If TRUE, the Quit command will always show
			a dialog, regardless of whether the config
			has changed or not. If FALSE, the dialog
			will never be shown. To get the old-style
			behaviour, with automatic dialog only if the
			config has changed, omit the argument.
