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 ).

< 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