Any-Agent Reference
AnyAgent is a generalized agent handler for handling system files
from /proc and /etc.
AnyAgent loads syntax description at startup to read and write
system file, loads complete file (incl. comments) to internal
YCPListRep and provides valid (i.e. non-comment) lines in another
data structure defined by syntax.
Commands
- Read
- Has the usual meaning.
- Write
- Before version 2.6.2 it returned 0 on success
and nil on error!
Since 2.6.2, it returns true or false.
Syntax Description
The syntax description is usually included in YCP-scripts and has
following body:
FIXME: the quoting varies widely. What is necessary and why?
`ag_anyagent (
Description (
source,
comment-chars,
is-read-only,
syntax,
headeropt
)
)
Where
- source
- is File ( string ) or Run ( string )
`arg (n): actually, there can be more arguments to Run - strings mixed
with `arg (n) terms, and these are substituted at Read time,
eg. Read (.foo, ["arg0", "arg1", "etc"])
- comment-chars
- is a string of comment characters. Lines beginning with any of
these characters are discarded. If Fillup ( string ) is
specified... FIXME, see Fillup.
- is-read-only
- a boolean. Some agents read from /proc, some syntax elements are read-only...
- syntax
- Syntax specification, see below.
- header
- FIXME: not implemented?
`anyagent(
``Description (
``< source >,
"< comment >", // Comment like "#\n"
< false|true >, // read-only
``
.... AnyAgent-commands....
)
)
), < path >);
description:
< source >
The source from which the information is read or in which it is written.
It could be a filename or a command ( program or shell-script ).
- File("< filename >")
- Run("< command >")
< path >
Path is the internal pathname of the script.
example: FIXME: old, fix quoting
`anyagent(
``Description (
``File("/etc/hosts"), // real file name
"#\n", // Comment
false, // read-only
``List (
Tuple (
`ip4 (Ip4Number()),
Separator ("\t "),
`hostnamess (List (Hostname(), Whitespace()))
),
"\n"
)
)
), .etc.hosts);
This example reads or writes the file /etc/hosts.
Syntax Elements
Alphabetically:
name
string
Boolean
Choice
Continue
Fillup
Float
Hexval
Hostname
Ip4Number
List
Match
Name
Number
Optional
Or
Separator
Sequence
Skip
String
Tuple
Username
Value
Var
Whitespace
Basic elements:
Float
Hexval
Hostname
Ip4Number
Number
String
Username
Other elements:
name
string
Choice
Continue
Fillup
List
Match
Name
Optional
Or
Separator
Sequence
Skip
String
Tuple
Value
Var
Whitespace
name
name ( syntax )
a term beginning with a lowercase letter means a map key
- Read:
- syntax is read and stored in the current Tuple as name
- Write:
- the map value keyed by name is written using syntax.
- See also:
- Tuple
- Examples:
-
string
a string
- Read, Write:
- Match or write the literal string.
- See also:
-
- Examples:
-
Boolean
Boolean ( )
- Read, Write:
- "yes" or "no", represented as a YCP boolean.
- See also:
-
- Examples:
-
Choice
Choice ( choice, ... )
Where each choice is a list: [ syntax1,
syntax2opt ]
- Read only:
- Like switch in C, tries to match syntax1 of each
choice. If a match is found, it is saved for use by Match and syntax2 is matched, if
it is provided.
- See also:
- Match
- Examples:
Continue
Continue ( syntax )
- Read:
- If used as a last element of Tuple, match syntax and
continue matching the same tuple, adding to the same map
- Write:
- ??? errorneous implementation, never used for writing.
- See also:
- Tuple
- Examples:
Fillup
Fillup ( )
Currently unused, probably intended for rc.config parsing?
- Read:
- A block of lines beginning with a comment character are assigned
to the current Tuple with a key FILLUP.
- Write:
- Within a Tuple, Fillup is written before the first "real" key.
- See also:
- Tuple
- Examples:
-
Float
Float ( )
- Read, Write
- An floating point number of the form /\d*\.?\d*/, represented as a
YCP float.
- See also:
-
- Examples:
-
Hexval
Hexval ( )
- Read, Write
- A hexadecimal integer, represented as a YCP integer. When reading, 0x
or 0X can be prepended.
- See also:
-
- Examples:
-
Hostname
Hostname ( )
- Read, Write
- A hostname, with or without a domain, represented as a YCP
string. Approximately [[:alpha:]][[:alnum:]_.]*
- See also:
-
- Examples:
-
Ip4Number
Ip4Number ( )
- Read, Write:
- IP4 address as nnn.nnn.nnn.nnn, represented as a YCP integer.
- See also:
-
- Examples:
-
List
List ( element-syntax, separator-syntax )
- Read:
- Match a list of element-syntax, separated by
separator-syntax. Separator-syntax must be a
terminal(?) (naturally). Return a YCP list of matches.
- Write:
- Write the provided list, properly separated. ??? Skip,
Fillup.
- See also:
- Examples:
Match
Match ( )
- Read only:
- Provides the match of the current Choice. Useful in a Name.
- See also:
- Choice, Name, Tuple
- Examples:
-
Name
Name ( syntax )
- Read only:
- Match syntax and use it as a map key in the current Tuple.
- See also:
- Value, Tuple
- Examples:
-
Number
Number ( )
- Read, Write
- An integer, represented as a YCP integer.
- See also:
-
- Examples:
-
Optional
Optional ( syntax )
- Read:
- Matches syntax, optionally.
- Write:
- Writes syntax, always.
- See also:
-
- Examples:
-
Or
Or ( syntax, ... )
- Read:
- Try to match syntax in given order, succeeds when the first
syntax matches.
- Write:
- Only for two alternatives (!?): write the first, or the second, if
the first results in an empty string.
- See also:
-
- Examples:
-
Separator
Separator ( string )
- Read:
- Match any characters contained in string.
- Write:
- Write the first character in string.
- See also:
- Whitespace, String, string
- Examples:
-
Sequence
Sequence ( syntax, ... )
- Read only:
- Match a sequence of syntaxes, return the string that
matched
- See also:
- Examples:
Skip
Skip ( )
A dummy element. Probably obsolete, used before Choice made the second
argument optional.
- Read:
- Read nothing
- Write:
- Write nothing
- See also:
- Choice
- Examples:
-
String
String ( charset-string, strip-stringopt )
- Read:
- Match a string consisting of characters from charset-string and
return it as a YCP string. If
charset-string starts with a "^", match characters not
in charset-string.
If strip-string is given (as a string constant !), these
characters are stripped from the match if they're found as leading
or trailing characters.
I.e. given the string " xxx xxx " matches String(" x") completely
and results in " xxx xxx ". With String(" x", " "), leading and
trailing blanks are stripped. So " xxx xxx " is still matched but
the result is "xxx xxx".
To match any string (rest of the line) use String ("^\n")
.
Empty matches are not allowed. If you want to match an empty string,
use Or (String (pattern), "")
instead of String (pattern)
.
In other words, String has a "+" repeat count, not "*".
- Write:
- When writing such values, stripping is also performed. So writing
" xxx xxx " results in the output of "xxx xxx"
- See also:
- Or
- Examples:
-
Tuple
Tuple ( syntax, ..., Continueopt )
- Read:
- Match a tuple of syntax descriptions. The matched data are
assigned to a map.
Tuples can be nested.
- Write:
- ??? (Skip, Fillup)
- See also:
- name, Name, Value, Match, Continue, Choice
- Examples:
- descr_info.scr
Username
Username ( )
- Read, Write
- A user name, represented as a YCP
string. Approximately [[:alpha:]][[:alnum:]]*
- See also:
-
- Examples:
-
Value
Value ( syntax )
- Read only:
- Match syntax and use it as a map value in the current Tuple.
- See also:
- Name, Tuple
- Examples:
-
Var
Var ( syntax, ... )
- Read:
- Match a sequence of syntaxes, ??? stopping in the middle
- Write:
- Write a sequence of syntaxes, ??? stopping in the middle
- See also:
- Name, Value
- Examples:
-
Whitespace
Whitespace ( )
- Read, Write:
- The same as Separator (" \t")
- See also:
- Separator
- Examples:
-
Martin Vidner, based on original
documentation by Klaus Kämpf