Lists

Lists are directories holding variables that the user can (basically) create and delete. In the context of lists, a variable may be also referred to as an element (or a list element).

It is possible to:

  • create,
  • delete,
  • rename,
  • copy,
  • move,
  • enable,
  • disable and
  • change the order of elements.

Elements defined by the same FCML file can be copied and moved between lists. In case of moving, this is equivalent to first copying the element to the target list and then deleting it. If you don't want to allow cross-copying and cross-moving, set the nocross property to yes.

Remarks for copying elements:

  • always generate a new elid (see below),
  • remember to delete all metadata of embedded version control system (if present).

Example:

# fs:/net/if/eth.fc

type = "list"
title = { en: "Ethernet interfaces" }

Definition of list element is held in listname.element.fc:

# fs:/net/if/eth.element.fc

type = "dir"
skel = "link ip tc vlan"

Note: in order to minimize the amount of rubbish in schema definitions, consider the existence of fs:/net/if/eth.element/ directory as optional in this case, ie. it should be possible to construct elements consisting of skeletons only (it's no use in creating an empty fs:/net/if/eth.element/ directory). This is why the type property should be explicitly set to dir here; obviously, we could deduce this from the skel property, but let's try to keep it that visible.

An element can be of any type except a list.

List order

A list has a special file, fc:listname/list.order which holds real element names and the order in which they should appear on it. This file has the following format (example):

1 eth0
3 ath0.5
#2 wlan4:3

Where:

  • a line starting with hash (#) means that the element is disabled (ie. the element is still there, but should be ignored until it's enabled again),
  • the numeric value until first space is called element id (or elid), and that's the name of the file physically holding the value of the element in the datatree,
  • arbitrary (non-zero) text after elid is the element name (or elname), provided by the user.

The last "feature" lets an element name to be a meaningful value, which sometimes may be enough (consider adding a DNS IP address to a list of DNS servers).

elids are unique and constant and the user is not able to modify them. This makes it easier to integrate version control. In order to assure elids uniqueness, use fc:/flatconf/counter (see basics).

elnames are unique, too. There is a special form of elname, "@![0-9]+" (e.g. "!@146"), what means the element with given elid (e.g. 146). Thus the only limitations of elnames are:

  • uniqueness,
  • cannot start with the 'at' sign (@),
  • cannot contain new line characters (\n).

Name suggestions for new elements

Sometimes it is needed to:

  • explain the user the meaning of a new element name, and/or
  • provide him with possible names for a new element.

Example:

type = "list"
title = { en: "DNS servers" }

namehint = { en: "DNS IPv4 address" }
examples = {
        { "208.67.222.222", en: "OpenDNS #1" },
        { "208.67.220.220", en: "OpenDNS #2" }
}
regexp = { "ipv4" }
  • namehint - contains multilingual hint for what the name means, similar to title,
  • examples - the same as the ''examples'' property in standard value properties, holds examples of elnames for new elements,
    • consider text autocompletion in textual interfaces,
  • strictnames - set this to 1 in order to force the user to choose an elname from examples,
    • in such case, the user interface may warn the user in case some already existing elname is not in examples (e.g. eth0 has been removed, but it's still in br0 bridge)

Note that ''regexp'' apply to the elname of a new element.

The examples property should contain all possibilities, ie. it is software's task to remove already existing elnames.

Remark: use FCML features and the examples property in FCML files to embed more logic into new name selection (e.g. adding a new interface to an Ethernet bridge should involve fetching the list of Ethernet interfaces present in the system/configuration).