Syntax Reference - rendaw/merman GitHub Wiki
This documentation describes the Lua configuration for Syntax.
Some values are typed. Specify types with built-in unary functions which take the value to be typed. For example, to place a dog in field animal, write dog { name = "fido" }. Types are indicated in the documentation as a word in parentheses.
Note that types only need to be specified where indicated.
Also, if a type only has one required field, the field can be filled directly, so:
repeat { count = 4 }may be shortened to:
repeat 4The root element of the document is:
SyntaxA tag that indicates editor state, such as "modified" when the document has unsaved changes.
The value of the tag.
| Values | Any string |
| Required | yes |
A tag that indicates an atom state, such as "compact".
The value of the tag.
| Values | Any string |
| Required | yes |
Show information about the atom hovered by the mouse.
Display the type of the atom.
| Values |
|
| Required | no |
| Default value | true |
Display the type of the atom part.
| Values |
|
| Required | no |
| Default value | true |
Show symbols in the gutter based on tags.
Separation between the symbol and the converse edge of the screen.
| Values | Any integer |
| Required | no |
| Default value | 0 |
If true, show the symbol by the near converse edge of the screen. Otherwise, the far.
| Values |
|
| Required | no |
| Default value | true |
Show a floating indicator symbol based on the current global and selection tags.
| Values | List of: Indicators$Indicator |
| Required | yes |
Separation between the symbol and the transverse edge of the screen.
| Values | Any integer |
| Required | no |
| Default value | 0 |
If true, show the symbols at the start of the gutter. Otherwise, the end.
| Values |
|
| Required | no |
| Default value | true |
An indicator is a single symbol that is shown or hidden based on active tags.
The symbol will have this type tag when shown.
| Values | Any string |
| Required | yes |
The symbol to show.
| Values | Any of (specify type):
|
| Required | yes |
Show the symbol when these tags are present.
| Values | Set of: Any of (specify type): |
| Required | yes |
Use Lua functions as actions.
A mapping of action names to Lua functions. Each function takes a single context argument and returns a boolean, true if the action modified the application state. context is an object with the following functions: act. act takes a string, the name of another action, and runs it, and returns true if the action modified the application state.
| Values | Nested: |
| Required | yes |
Show information about the atom the cursor's in
The format of the text to display in the banner.
| Values | Format |
| Required | yes |
Hotkey definitions that are enabled based on tags.
Text keys that don't match a hotkey are passed to the selected primitive.
| Values |
|
| Required | no |
| Default value | true |
Hotkeys to use when the tags match.
| Values | Nested: List of: Any of (specify type): |
| Required | yes |
These tags must be present.
| Values | Set of: Any of (specify type): |
| Required | yes |
These tags must be absent.
| Values | Set of: Any of (specify type): |
| Required | no |
Trigger actions with keyboard and mouse button presses.
A list of hotkey rules.
| Values | List of: HotkeyRule |
| Required | no |
Show the current input sequence and possible actions when an input is received in an incomplete sequence.
| Values |
|
| Required | no |
| Default value | true |
Any type of binary input.
-
mouse1 -
mouse2 -
mouse3 -
mouse_scroll_up -
mouse_scroll_down -
enter -
backspace -
tab -
cancel -
clear -
shift -
control -
alt -
pause -
caps -
escape -
space -
page_up -
page_down -
end -
home -
left -
up -
right -
down -
comma -
minus -
period -
slash -
0 -
1 -
2 -
3 -
4 -
5 -
6 -
7 -
8 -
9 -
semicolon -
equals -
a -
b -
c -
d -
e -
f -
g -
h -
i -
j -
k -
l -
m -
n -
o -
p -
q -
r -
s -
t -
u -
v -
w -
x -
y -
z -
open_bracket -
back_slash -
close_bracket -
numpad0 -
numpad1 -
numpad2 -
numpad3 -
numpad4 -
numpad5 -
numpad6 -
numpad7 -
numpad8 -
numpad9 -
multiply -
add -
separator -
subtract -
decimal -
divide -
delete -
num_lock -
scroll_lock -
f1 -
f2 -
f3 -
f4 -
f5 -
f6 -
f7 -
f8 -
f9 -
f10 -
f11 -
f12 -
f13 -
f14 -
f15 -
f16 -
f17 -
f18 -
f19 -
f20 -
f21 -
f22 -
f23 -
f24 -
printscreen -
insert -
help -
meta -
back_quote -
quote -
kp_up -
kp_down -
kp_left -
kp_right -
dead_grave -
dead_acute -
dead_circumflex -
dead_tilde -
dead_macron -
dead_breve -
dead_abovedot -
dead_diaeresis -
dead_abovering -
dead_doubleacute -
dead_caron -
dead_cedilla -
dead_ogonek -
dead_iota -
dead_voiced_sound -
dead_semivoiced_sound -
ampersand -
asterisk -
quotedbl -
less -
greater -
braceleft -
braceright -
at -
colon -
circumflex -
dollar -
euro_sign -
exclamation_mark -
inverted_exclamation_mark -
left_parenthesis -
number_sign -
plus -
right_parenthesis -
underscore -
windows -
context_menu -
final -
convert -
nonconvert -
accept -
modechange -
kana -
kanji -
alphanumeric -
katakana -
hiragana -
full_width -
half_width -
roman_characters -
all_candidates -
previous_candidate -
code_input -
japanese_katakana -
japanese_hiragana -
japanese_roman -
kana_lock -
input_method_on_off -
cut -
copy -
paste -
undo -
again -
find -
props -
stop -
compose -
alt_graph -
begin -
undefined -
softkey_0 -
softkey_1 -
softkey_2 -
softkey_3 -
softkey_4 -
softkey_5 -
softkey_6 -
softkey_7 -
softkey_8 -
softkey_9 -
game_a -
game_b -
game_c -
game_d -
star -
pound -
power -
info -
colored_key_0 -
colored_key_1 -
colored_key_2 -
colored_key_3 -
eject_toggle -
play -
record -
fast_fwd -
rewind -
track_prev -
track_next -
channel_up -
channel_down -
volume_up -
volume_down -
mute -
command -
shortcut
Match each subpattern in order.
The list of rules to match in sequence.
| Values | List of: Any of (specify type): |
| Required | yes |
Match a single key.
The input that is being pressed or released.
| Values | Key |
| Required | yes |
Inputs that must be active for this rule to match.
| Values | Set of: Key |
| Required | no |
True if the input is pressed, false if the input is released.
| Values |
|
| Required | no |
| Default value | true |
Match any of the subpatterns.
All rules that may match.
| Values | List of: Any of (specify type): |
| Required | yes |
A general syntax defined atom type.
Create alignments in the atom with the mapped ids.
| Values | Nested: Any of (specify type):
|
| Required | yes |
When filling a suffix or prefix gap, the resultant atom will be raised up the tree based on its associativity. For example, suppose in the document a + b you type + c. If + is back associative, the resultant tree will be equivalent to (a + b) + c. If + is front associative, the resultant tree will be equivalent to a + (b + c). This is a translation of mathematical operator associativity. Associativity only applies to atoms of the same precedence.
| Values |
|
| Required | no |
| Default value | false |
If this type is a suggestion and there are less than this many choices, auto-choose this type.
| Values | Any integer |
| Required | no |
| Default value | 1 |
This describes the format of the data on disk. Modifiable back parts must have a corresponding middle part.
| Values | List of: Any of (specify type):
|
| Required | yes |
When calculating depth for windowing, this is the value the atom increases the depth score by.
| Values | Any integer |
| Required | no |
| Default value | 0 |
This describes how the atom is represented in the editor. Modifiable must have a corresponding middle part.
| Values | List of: Any of (specify type):
|
| Required | yes |
The id of the atom type. This must be unique among atom types and groups.
| Values | Any string |
| Required | yes |
The editable data this atom contains.
| Values | Nested: Any of (specify type):
|
| Required | yes |
A name for human consumption.
| Values | Any string |
| Required | yes |
When filling a suffix or prefix gap, the resultant atom will be raised up the tree
| Values | Any integer |
| Required | no |
| Default value | 2147483647 |
Tags for this atom.
| Values | Set of: Any string |
| Required | yes |
A gap.
Front parts to add before the gap text.
| Values | List of: FrontSymbol |
| Required | yes |
Front parts to add after the gap text.
| Values | List of: FrontSymbol |
| Required | yes |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
Padding around source content (not including banner, details, indicators, etc).
Pad the converse end by this many pixels.
| Values | Any integer |
| Required | no |
| Default value | 0 |
Pad the converse start by this many pixels.
| Values | Any integer |
| Required | no |
| Default value | 0 |
Pad the transverse end by this many pixels.
| Values | Any integer |
| Required | no |
| Default value | 0 |
Pad the transverse start by this many pixels.
| Values | Any integer |
| Required | no |
| Default value | 0 |
A gap that wraps a child atom. Fills to an atom that prefixes the child atom.
Front parts to add between the gap text and child atom.
| Values | List of: FrontSymbol |
| Required | no |
Front parts to add before the gap text.
| Values | List of: FrontSymbol |
| Required | no |
Front parts to add after the child atom.
| Values | List of: FrontSymbol |
| Required | no |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
The type of the root atom. In luxem documents, the root atom itself is outside the document, but the array (or whatever values it holds) become the document's root.
See FreeAtomType.
| Values | Nested: Any of (specify type):
|
| Required | yes |
See FreeAtomType.
| Values | List of: Any of (specify type):
|
| Required | yes |
See FreeAtomType.
| Values | List of: Any of (specify type):
|
| Required | yes |
See FreeAtomType.
| Values | Nested: Any of (specify type):
|
| Required | yes |
See FreeAtomType.
| Values | Set of: Any string |
| Required | yes |
A gap that wraps a child atom. Fills to an atom that suffixes the child atom.
Front parts to add between the gap text and child atom.
| Values | List of: FrontSymbol |
| Required | no |
Front parts to add before the child atom.
| Values | List of: FrontSymbol |
| Required | no |
Front parts to add after the gap text.
| Values | List of: FrontSymbol |
| Required | no |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
A syntax describes the de/serialization, interaction, and display of a document. A document is a syntax tree encoded as luxem or JSON. The syntax breaks the tree up into atoms which are the basis for interaction and display.
A merman syntax file is a Lua script that returns a table describing the syntax. When you open a source file in merman, it automatically loads the corresponding syntax file from ~/.config/merman/syntaxes (~/Library/Preferences/merman/syntaxes on Mac, something like c:UsersUserAppDatamermansyntaxes on Windows - syntax_luxem.lua is placed there the first time you run merman so you can search for that) based on the source file extension.
Slide courses into position.
| Values |
|
| Required | no |
| Default value | false |
Slide the contents of the details pane when it changes.
| Values |
|
| Required | no |
| Default value | false |
The background color of the document.
| Values | Any of (specify type):
|
| Required | no |
Pad the banner pane.
| Values | Padding |
| Required | no |
The direction of text flow in a line. For English, this will be RIGHT. Note that values other than RIGHT may not work, since JavaFX has limited text direction support.
| Values | Syntax$Direction |
| Required | no |
| Default value | right |
Pad the detail pane.
| Values | Padding |
| Required | no |
The max transverse span for details panes, excluding padding.
| Values | Any integer |
| Required | no |
| Default value | 300 |
Limit the window to this depth span.
| Values | Any integer |
| Required | no |
| Default value | 2147483647 |
The gap type is used when editing the document, for new data whose type is not yet known.
| Values | GapAtomType |
| Required | no |
Style of the gap choice selection box.
| Values | BoxStyle |
| Required | no |
Placeholder for text in gap choice previews.
| Values | Any of (specify type):
|
| Required | no |
Pseudo-types representing groups of types. Group ids can be used anywhere a type id is required.
| Values | Nested: List of: Any string |
| Required | no |
Generate bricks in this batch size when jumping, scrolling, and editing.
| Values | Any integer |
| Required | no |
| Default value | 10 |
A list of modules to activate. Listed are modules bundled with this distribution, but addional modules may be installed and used.
| Values | List of: Any of (specify type):
|
| Required | no |
Pad the document.
| Values | Padding |
| Required | no |
Character to substitute for non-printing characters in primitives.
| Values | Any string |
| Required | no |
| Default value | ▢ |
The prefix gap type is similar to the gap type, but is used when enclosing an existing atom in a new atom, where the new atom visually precedes the existing atom.
| Values | PrefixGapAtomType |
| Required | no |
Add spaces to make human reading of the source easier.
| Values |
|
| Required | no |
| Default value | false |
Retry course expansion when converse deficit has increased by this factor.
| Values | Any decimal value |
| Required | no |
| Default value | 1.25 |
The type of the root array in a document. This is not used when pasting code; in that case the context is used to determine the paste's potential root type.
| Values | RootAtomType |
| Required | yes |
The percentage of the screen transverse span to jump when scrolling alot.
| Values | Any decimal value |
| Required | no |
| Default value | 0.8 |
The percentage of the screen transverse span to jump when scrolling.
| Values | Any decimal value |
| Required | no |
| Default value | 0.1 |
When opening a document, immediately restrict the window to the tree that starts at the root atom.
| Values |
|
| Required | no |
| Default value | false |
Styles control how bricks and other visual elements (selection, hover, banner, details, indicators, etc) are displayed. When a visual element is styled, each style's tags are compared to the brick's tags in turn. A composite style is built by merging the properties of each matching style, with later matching style properties overriding earlier properties.
Each brick assumes a number of tags from their corresponding front parts, atom types, and any global tags. Selection and hover visuals assume the tags of the relevant front part and any global tags. The banner assumes the part tag banner and any global tags. The details assume the part tag details and any global tags. In addition to the details tag, if the details contain a selection, the choices additionally assume part tag details_choice and the selection assumes part tag details_selection.
| Values | List of: Style |
| Required | no |
The suffix gap type is similar to the gap type, but is used when enclosing an existing atom in a new atom, where the new atom visually succeeds the existing atom.
| Values | SuffixGapAtomType |
| Required | no |
The direction of successive lines. For English, this will be DOWN.
| Values | Syntax$Direction |
| Required | no |
| Default value | down |
The encoding of source files with this syntax.
| Values | Syntax$BackType |
| Required | no |
| Default value | luxem |
The definitions of all distinct element types in a document.
A type with the id '__gap' and a single middle primitive element named 'value' must exist. This will be used as a placeholder when entering text before it is distinguishable as any other defined element.
| Values | List of: FreeAtomType |
| Required | yes |
The encoding of source files.
-
luxemBack parts and source files are in luxem format. -
jsonBack parts and source files are in JSON format.
Aligns bricks a fixed offset from the converse start of the screen.
Offset in pixels.
| Values | Any integer |
| Required | yes |
Aligns bricks with an offset relative to another alignment.
The id of the base alignment.
| Values | Any string |
| Required | yes |
The difference between this alignment and this base in pixels.
| Values | Any integer |
| Required | yes |
A fixed array.
This sequence of elements will appear in the source file.
| Values | List of: Any of (specify type):
|
| Required | yes |
An editable value.
Read the array into or write from the middle array with this id.
| Values | Any string |
| Required | yes |
An editable value.
Read the child atom into or write from the middle atom with this id.
| Values | Any string |
| Required | yes |
An editable value. Only valid with a JSON back type.
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
An editable value. Only valid with a JSON back type.
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
A key in an array.
Read the key into or write from the middle primitive with this id.
| Values | Any string |
| Required | yes |
Read the primitive into or write from the middle primitive with this id.
| Values | Any string |
| Required | yes |
An editable record.
Read the record into or write from the middle array with this id.
| Values | Any string |
| Required | yes |
An editable value. De/serializes an array in luxem that has no begin [ and end ]. This may only be used in the root atom type.
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
An editable luxem type.
Read the type into or write from the middle primitive with this id.
| Values | Any string |
| Required | yes |
| Values | Any of (specify type):
|
| Required | yes |
A fixed record.
| Values | Nested: Any of (specify type):
|
| Required | yes |
A fixed luxem type.
The type string.
| Values | Any string |
| Required | yes |
| Values | Any of (specify type):
|
| Required | yes |
Formats a string which is the concatenation of all elements.
| Values | List of: Any of (specify type): |
| Required | yes |
Text provided dynamically. Reference names depend on context - look at specific usages for valid names.
| Values | Any string |
| Required | yes |
Show or hide a front part based on properties of the atom.
Invert is.
| Values |
|
| Required | no |
| Default value | false |
The condition in which to show this front item.
| Values | ConditionNode$Is |
| Required | yes |
Show or hide a front part based on properties of a value within an atom.
Invert is.
| Values |
|
| Required | no |
| Default value | false |
The condition in which to show this front item.
| Values | ConditionValue$Is |
| Required | yes |
The id of the middle part that the condition is based on.
| Values | Any string |
| Required | yes |
Display an array of child atoms.
How to visualize the ellipsis.
| Values | Any of (specify type):
|
| Required | no |
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
What to display before every element in the array.
| Values | List of: FrontSymbol |
| Required | no |
What to display between every two elements in the array.
| Values | List of: FrontSymbol |
| Required | no |
What to display after every element in the array.
| Values | List of: FrontSymbol |
| Required | no |
Add the part tag with value first to the first element.
| Values |
|
| Required | no |
| Default value | false |
Add the part tag with value last to the last element.
| Values |
|
| Required | no |
| Default value | false |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
Display a child atom.
How to visualize the ellipsis.
| Values | Any of (specify type):
|
| Required | no |
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
Tags for this front part. These are only used as context when the selection is in this part.
| Values | Set of: Any string |
| Required | yes |
Display text data.
The id of the corresponding middle part.
| Values | Any string |
| Required | yes |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
Add free tags with these values.
| Values | Set of: Any string |
| Required | yes |
Display a fixed symbol (text, space, image).
Only display this front element when the condition is matched. A symbol's text will be used to match the atom type when filling a gap. This symbol will be ignored though if it has a condition which is off by default.
| Values | Any of (specify type):
|
| Required | no |
Use this string as a key for matching the atom when filling a gap. This is intended for symbols that do not contain text (image) but it may also be used to override the text in a text node.
| Values | Any string |
| Required | no |
| Default value | |
Add these tags to the symbol's brick.
| Values | Set of: Any string |
| Required | yes |
The type of symbol.
| Values | Any of (specify type):
|
| Required | yes |
This defines the pattern that the text of the primitive takes. Note that if specified, the pattern will be checked every time the primitive is modified. On long primitives this can be very slow.
| Values | Any of (specify type):
|
| Required | no |
A record is effectively an array with elements that have record keys.
The id of the type of the record elements.
| Values | Any string |
| Required | yes |
Match the subpattern 0 or 1 times.
| Values | Any of (specify type):
|
| Required | yes |
Match each subpattern in sequence.
| Values | List of: Any of (specify type):
|
| Required | yes |
An easy way to construct a sequence of characters.
The character sequence to match.
| Values | Any string |
| Required | yes |
Match any one subpattern.
| Values | List of: Any of (specify type):
|
| Required | yes |
Repeat the subpattern 0 or more times.
| Values | Any of (specify type):
|
| Required | yes |
Repeat the subpattern 1 or more times.
| Values | Any of (specify type):
|
| Required | yes |
Properties if the style is applied to a box.
Fill the box.
| Values |
|
| Required | no |
Color of the fill.
| Values | Any of (specify type):
|
| Required | no |
Outline the box.
| Values |
|
| Required | no |
Color of the outline.
| Values | Any of (specify type):
|
| Required | no |
Thickness of the outline in pixels.
| Values | Any decimal value |
| Required | no |
Distance fron the contents to the edge of the box in pixels.
| Values | Any integer |
| Required | no |
Round the end corner.
| Values |
|
| Required | no |
Round the outer corners.
| Values |
|
| Required | no |
Round each rounded corner by this radius.
| Values | Any integer |
| Required | no |
Round the start corner.
| Values |
|
| Required | no |
An RGB color. Values are between 0 and 1, inclusive, with 1 being maximum intensity.
Blue
| Values | Any decimal value |
| Required | yes |
Green
| Values | Any decimal value |
| Required | yes |
Red
| Values | Any decimal value |
| Required | yes |
An RGB color with alpha. Values are between 0 and 1, inclusive, with 1 being maximum intensity.
Alpha. 1 is opaque, 0 is transparent.
| Values | Any decimal value |
| Required | yes |
Blue
| Values | Any decimal value |
| Required | yes |
Green
| Values | Any decimal value |
| Required | yes |
Red
| Values | Any decimal value |
| Required | yes |
Properties if the style is applied to an obbox (a disjoint box that may start and end on different lines).
Fill the obbox.
| Values |
|
| Required | no |
Fill color.
| Values | Any of (specify type):
|
| Required | no |
Outline the obbox.
| Values |
|
| Required | no |
Color of the outline. Also used for the cursor when there is no selection.
| Values | Any of (specify type):
|
| Required | no |
Thickness of the outline in pixels. Also used for the cursor when there is no selection.
| Values | Any decimal value |
| Required | no |
Distance from the contents to the edge of the obbox in pixels.
| Values | Any integer |
| Required | no |
Round concave corners.
| Values |
|
| Required | no |
Round the end corner.
| Values |
|
| Required | no |
Round the inner corners.
| Values |
|
| Required | no |
Round the outer corners.
| Values |
|
| Required | no |
Round each rounded corner by this radius.
| Values | Any integer |
| Required | no |
Round the start corner.
| Values |
|
| Required | no |
All properties required to style a visual element.
Align the converse start with the nearest alignment with this id. The alignment is sought starting at the element's parent and moving upwards to the root of the window/document.
| Values | Any string |
| Required | no |
This only applies to boxes.
| Values | BoxStyle |
| Required | no |
This only applies to text.
| Values | Any of (specify type):
|
| Required | no |
The font family name (JavaFX). This only applies to text.
| Values | Any string |
| Required | no |
This only applies to text.
| Values | Any integer |
| Required | no |
The filename of the image, either absolute or relative to the syntax directory. This only applies to image symbols.
| Values | Any string |
| Required | no |
This only applies to obboxes.
| Values | ObboxStyle |
| Required | no |
Rotation of the image, presumably in degrees.
| Values | Any integer |
| Required | no |
The converse span of a space symbol.
| Values | Any integer |
| Required | no |
Add a converse space of this many pixels after the element.
| Values | Any integer |
| Required | no |
Add a converse space of this many pixels before the element.
| Values | Any integer |
| Required | no |
Add a transverse space of this many pixels after the element.
| Values | Any integer |
| Required | no |
Add a transverse space of this many pixels before the element.
| Values | Any integer |
| Required | no |
Start this element on the next line.
| Values |
|
| Required | no |
These tags must be present.
| Values | Set of: Any of (specify type): |
| Required | yes |
A style will apply to a brick if both the brick and the global tags contain none of these.
| Values | Set of: Any of (specify type): |
| Required | no |