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,
	header_opt
    )
)

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, syntax2_opt ]

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

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".
Empty matches are not allowed. If you want to match an empty string, use Or (String ("^\n"), "") instead of String ("^\n").
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, ..., Continue_opt )

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