MSL expressions in general take the form: key selector value transform.
A key refers to an atom which is unique inside its lexical context.
A selector can be used to access metadata or text inside the atom.
A value replaces the previous value of a key or selector.
A transform takes in the current value and can return a new one to replace it.
An expression is a setter if a value is provided, otherwise it's a getter. A transform which returns a value acts like a value in the rest of the expression. A containing MSL expression cannot be resolved and processing stops if any of its inner expressions cannot be resolved by the hybrid database. When moving expressions between containing atoms, such as two views in the same machine or two streams from separate machines, expressions must be resolved in the source context and then resolved again in the destination context. This gives the destination viewer the ability to resolve these atoms against known canon and add or discard the new information as the user desires.
key ⇒ gets the atom (getter)
key selector ⇒ gets the selector on the atom (getter)
key transform ⇒ transforms the atom in the viewer (getter)
key selector transform ⇒ transforms the selector in the viewer (getter)
key bracketed-transform ⇒ transforms the atom's value (setter)
key selector bracketed-transform ⇒ transforms the selector's value (setter)
key value ⇒ sets the atom's value (setter)
key value transform ⇒ sets the atom's value and transforms it in the viewer (setter)
key selector value ⇒ sets the selector's value (setter)
key selector value transform ⇒ sets the selector's value and transforms it in the viewer (setter)
Here are some examples which demonstrate the basic relationships between keys, selectors, values, and transforms. We assume the following canon already exists in the stream:
(c disney-canon
(@WALT Walt Disney :fullname Walter Elias Disney :wife (@LILLIANDISNEY))
(@LILLIANDISNEY Lillian Disney))
Although the full (@WALT) atom is available to the viewer and the engine, a typical viewer will most likely display the text value of the atom. This is a getter and no values are set:
//key – gets the atom (getter)
(@WALT) ⇒ Walt Disney
The viewer and engine have access to the full (@LILLIANDISNEY) atom, but a viewer would normally display the value of that atom, Lillian Disney, in a paragraph where this syntax appeared:
//key selector – gets the selector on the atom (getter)
(@WALT :wife) ⇒ Lillian Disney
A transform acts in the viewer to change the appearance of a value or to supply a new one. In this case, the (f bold) format function causes the text to appear in bold but does not provide a return value so it is a getter:
//key transform – transforms the atom in the viewer (getter)
(@WALT (f bold)) ⇒ Walt Disney
The transform [filespec] is used to load the value from a file reference. The result of the transform, the value loaded from the file, becomes the value for (@WALT). This is a setter:
//key bracketed-transform – transforms the atom's value (setter)
(@WALT [file:///c:/documents/disney/walt-atom.msl])
The formatting expression (f bold) is applied to the value returned from the :fullname metadata-key, making it bold in the viewer. This transform does not return a value:
//key selector transform – transforms the selector in the viewer (getter)
(@WALT :fullname (f bold)) ⇒ Walter Elias Disney
A book's PDF file is loaded into the view's :pdf metadata-key by this [filespec] transform:
//key selector bracketed-transform – transforms the selector's value (setter)
(v vinyl-leaves Vinyl Leaves :pdf [file:///c:/disney/vinyl-leaves.pdf])
In this next example, the full atom with the changed value is available, though the viewer will likely show only the changed value. The original value is still available in the canon.
//key value – sets the atom's value (setter)
(@WALT Walter E. Disney) ⇒ Walter E. Disney
MSL parameters are evaluated differently from other languages in order to meet the language's goals, including readability first. Parameters in MSL expressions are evaluated or "consumed" by other parameters according to the following rules:
A selector consumes (takes as its value) everything before the selector.
An atom consumes nothing.
A value consumes everything up to the next selector, transform, or comment.
A transform consumes everything up to the next selector, transform, or comment.
A comment consumes everything up to the end of the expression.