The most important selector is the metadata selector. Metadata is a list of keys and values belonging to an atom. It can be set or recalled with the :metadata-key syntax. The space before the colon is optional and can be omitted when only one metadata-key is being set or retrieved.
Metadata is often used to store factual information that's associated with the atom. An atom representing a person might have metadata for his birthday, for example. Here are some sample atoms that represent elements in the periodic table with four pieces of data stored for each. The first parameter is the atom value and the others are metadata:
(@H hydrogen :no 1 :symbol H :weight 1.008)
(@Li lithium :no 3 :symbol Li :weight 6.94)
(@Na sodium :no 11 :symbol Na :weight 22.990)
We can recall any part of the metadata:
(@H) ⇒ hydrogen
(@H:symbol) ⇒ H
(@Na :weight) ⇒ 22.990
(@Li) #(@Li:no) ⇒ Lithium #3
This next example is factually incorrect since we know the atomic number of lithium is 3, not 7. Values like this which are known to be factually correct can be protected by a canon expression.
(@Li:no 7) ⇒ 7
Setting a metadata value changes the value in that expression and going forward:
1. (@tokyo-disneyland :rides (@pooh Pooh's Hunny Hunt) (@nemo …))
2. (@tokyo-disneyland :rides) ⇒ Pooh's Hunny Hunt ...
The following definition of (@ENGELBART) relies on the existence of (@NLS) and (@Portland) inside the same containing expression, in this case (v ui-paper).
(v ui-paper
(@NLS NLS)
(@Portland Portland)
(@ENGELBART Douglas Engelbart :birthplace (@Portland) :software (@NLS)))
It results in the atom's value becoming Douglas Engelbart, his :birthplace becoming Portland, and his :software becoming NLS from this expression going forward.
(@DOUGLASENGELBART :software) ⇒ NLS
The full definition of (@ENGELBART) contains both a value and metadata selectors. Atoms like these can be viewed in several ways by the same viewer, allowing editing of metadata in a property sheet, for example. The viewer has full access to the atom's value and the values of all its metadata, but in narrative text a single value is returned according to the following rules:
(@ key) ⇒ return the value of the atom
(@ key value) ⇒ set the atom's value and return it
(@ key selector) ⇒ return the result of the selector on the atom
(@ key selector value) ⇒ set the selector to the value and return it
(@ key value selector value) ⇒ set the atom's value and the selector's value and return the atom's value
These examples show all five varieties of rendering in reverse order because 5 is the defining type used to fully define an atom.
Example 5 above contains three selectors and values for each of them. It also contains a value for the atom so that is what it returns:
//example 5
(@miss-clairol-27 Lightly Blonde :no 27 :family blonde :box [file:///c:/box/clairol/miss-clairol/27.jpg]) ⇒ Lightly Blonde
Example 4 contains a selector and its value. It also contains a value for the atom so that is what it returns:
//example 4
(@miss-clairol-27 Lightly Blonde :no 27) ⇒ Lightly Blonde
Example 3 contains only a selector, so it returns the selector value, in this case, a photo:
//example 3
(@miss-clairol-27 :box) ⇒ [file:///c:/box/clairol/miss-clairol/27.jpg]
Example 2 contains only a value, so it returns the value. This is an example of how any paragraph text can be linked to an atom:
//example 2
(@miss-clairol-27 blonder than Bond) ⇒ blonder than Bond
Example 1 contains only a key so it retrieves the last value. The atom was recently redefined to this value. If the atom were wrapped in canon, however, this would not be the case. Canon protects atoms against incidental changes, always providing a fallback value.
//example 1
(@miss-clairol-27) ⇒ blonder than Bond