2002-08-01 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 clear bool If TRUE, the contents of the path text entry box are removed before being focused. 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. DpReorient Keyword Type Description orient enum If value is "h", "horiz", or "horizontal", set pane split to horizontal (the "classic" mode). If it's "v", "vert" or "vertical", set it to vertical. If absent, the mode is toggled to whichever isn't the current one. quiet bare If present, the change of the orientation will not "dirty" the configuration. MenuPopup Keyword Type Description atfocus bare If included, the gentoo will attempt to position the menu over the currently focused row, rather than at the mouse pointer position. If no focused row exists, the menu is centered in the pane. menu string Name of menu to pop up. The only name currently supported is the default, "DirPaneMenu". 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.