1999-11-21
							Emil Brink

		Arguments 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.
		      pageprev	Move bar up roughly one pageful
				of rows.
		      pagenext	Move the bar down a rough page.
			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.

NOTE	The "pageprev" and "pagenext" movements are not exactly
	well implemented. Consider them a rough hack, and use them
	only with that in mind. Thanks.


DpGotoRow
Keyword		Type	Description
re		string	This lets you specify a pattern using the
			usual regular expression syntax. The first
			row whose file name matches the pattern will
			be scrolled into view. There is no requirement
			that the expression matches the entire filename,
			nor is there a requirement that it matches from
			the start. To get the latter, just prefix the
			RE with the circumflex (^) symbol, as usual. To
			get the former, postfix a dollar ($) sign as
			well.
row		integer	This lets you specify the index of the row you
			wich to go to, rather than using a regular
			expression to select it. Only one of 're' and
			'row' may be used at a time. If both are specified,
			're' takes precendence.
focus		bool	If TRUE, the target row will be focused in
			addition to being made visible.
nocase		bool	If TRUE, the regular expression matching is
			done without regard for case differences. If
			FALSE, as is the default, case matters.


DpFocusPath
Keyword		Type	Description
select		bool	If TRUE, the contents of the path text entry box
			will be selected in addition to focused.


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".
content		enum	Selects the content to match against. Must
			be a single mnemonic word that signifies the
			content type. The following types of content
			are currently recognized:
			name		nlink		devmin
			size		uid		atime
			smartsize	uname		mtime
			blocks		gid		ctime
			blocksize	gname		type
			modenum		device		(icon)
			modestr		devmaj
			The use of "icon" as content is discouraged.
			Hopefully, these shortened names should be
			understandable.
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.

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


SelectRow
Keyword		Type	Description
row		number	Specify the number of the row you wish to have
			selected. Only a single row can be specified.
			You can use the "0x" prefix for hexadecimal
			row numbers, if you're so inclined.

action		enum	Should be one of "select", "unselect", and
			"toggle". Hopefully self-explanatory.

NOTE	If the "row" keyword is _not_ specified, gentoo will use whatever
	row was last clicked (in any pane, not necessarily the current one).
	This is kind of tricky to use correctly, but works well when put
	in sequence with a "MenuPopup" and bound to the right mouse button
	in panes. This emulates Windows right-clicking, which is sometimes
	neat.


SelectSuffix
Keyword		Type	Description
action		enum	Controls what will be done to rows whose names
			end in the same suffix as either the row you
			clicked or the focused row. Can be "select",
			"unselect" or "toggle". Self-explanatory?


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.