| Filename | Latest commit message | Latest commit date |
|---|---|---|
| README.md | ||
Intact Specification
This document describes, explains and shows all base Intact features. Intact's syntax is derived from XML, which makes implementation easy, as parsing a layout only requires it being turned into valid XML, after which it can be read by any existing library!
The extension of a file is irrelavant, but heres some of my suggestions:
.ui(this is what I use).tc
// Change the current namespace (ideally the usage of this is limited to once per file)
<namespace "Main">
// Import other namespaces
<import "MyComponent">
<import "MyImageComponent">
<import "MyContentComponent">
<root> // Main element! This is the object that gets returned when the file is rendered!
<stack> // Directional stack container, goes horizontally (x) or vertically (y)
<MyComponent>
<MyImageComponent source="file.png">
</stack>
// Text. Should equal to the resulting language's most lightweight representation
// of text. In HTML this would just be pure plaintext without element.
<text>Hello INTACT!</text>
// Text without a parent...
like this
// ...will also get translated into <text>.
<MyContentComponent>
This component is able to have child objects!
</MyContentComponent>
<MyContentComponent/> // But in this case doesn't have to.
<stack x> // Horizontal flag
<MyImageComponent source="1.png">
<MyImageComponent source="2.png">
<MyImageComponent source="3.png">
</stack>
<>
// Group objects. Cannot have any attributes and are purely used for
// if a collecton of elements needs to be addressed as a single object
// (as an example: the content value of a component)
// They ungroup the objects once rendered.
</>
</root>
// Namespace for this component
<namespace "HelloWorld">
<MyHelloWorldComponent>
<text>Hello World!</text>
</MyHelloWorldComponent>
Terminology
XML Terminology mostly applies, except that nodes are instead referred to as objects, and the document is instead referred to as the layout.
Whitespace is allowed in all places where it makes sense.
Actual definitions of where it should be allowed will be on the Intact wiki once it exists.
Layout structure
Intact doesn't have a traditional "root" object.
The <root> object is the part of the layout that gets processed when it is rendered.
Components are defined alongside this root object.
<root>
...
</root>
<Component1 ...>
...
</Component1>
<Component2 ...>
...
Additional meta information
(e.g.: styles, scripts, descriptions, ... (depending on the implementation))
can be added in the <root> object under the <meta> parent object.
In XML: Layout is wrapped in a <intact> object.
Comments
C-style comments are supported alongside XML comments.
// Example comment
/*
Example multi-line comment
*/
<!-- Example comment -->
In XML: Every comment is turned into XML-style comments.
Flags
A component object can be given flags as attributes. (e.g.: <Button disabled>)
Flags in components are always optional. (attr:flag = attr?:flag)
<Component ... <flag> ...>
In XML: Since XML doesn't support attributes without value, assign each flag attribute an empty string: flag="".
Numbers and Integers
An object's attribute can be assigned a number or an integer
without having to wrap the value in quotes. (e.g.: attribute=42, attribute=3.14)
In XML: See the Extended Attribute format.
Types
stringorstr: string value, like XML (default) - if the value assigned to variable or attribute of this type isn't a string, it's converted into onenumberornum: floating-point numerical valueintegerorint: integer numerical valuebooleanorbool: true or false value, must be eithertrueandfalse,TrueandFalse, or0and1objectorobj: a layout object (inserted through code, value orchildrencomponent attribute) - can be inserted inside an object and iterated over, and, if the object is a<group>, it can be indexedlist: a list of mixed* values (only insertable through code or function calls)<type>-list: a list of values with specified type* (only insertable through code or function calls)tableortbl: a key-value table, indexable with said key (only insertable through code or function calls)flag: component-exclusive value that can be used like a boolean -trueif it has been provided to a component<string> | <string> ...: only allows certain values (e.g.:type:"info"|"warning"|"error",size:"big"|"small"). Enums should be converted into this type.
* Supported types for lists: string, number, integer, boolean, object, list and <type>-list
Type Annotation
In some cases the attributes of an object support/need a set type. As of now that only includes:
If there is no annotation, the default type for all attributes is string.
The type annotation sits inbetween the attribute name and value:
<name>:<type>=<value>
In XML: See the Extended Attribute format.
Components
Components are reusable layouts that you can use inside of other layouts. The tag name of a root-level element in a layout file is the name of the component, which must start with an uppercase letter.
You can specify required and optional attributes inside the opening tag of the component (with type annotations).
- For optional attributes, put a
?after the name:<name>?:<type><name>?. - For defaults, simply assign a value to the attribute (e.g.:
attr:string="default value"). Doing this also removes the need to explicitly mark an attribute as optional*. All attributes given to a component object will be added to its context when it is rendered.
* If you use an empty string ("") as the default value for a string attribute,
you need to explicitly define the type of that attribute as a string (attr:string=""),
or as optional (attr?="") due to conflicts with parsing flags.
To make a component able to be used as a parent object, you can give it the attribute children:object.
You can also make having children optional: children?:object.
For further use of the object type, see here.
In order to use components without providing them through code, they must belong to a namespace.
You can change the current namespace using <namespace "<name>"> (e.g.: <namespace "buttons">).
The namespace can be in any format you prefer, as long as it doesn't contain spaces.
(A few ideas: appname:buttons, com.example.AppName.Buttons, example.buttons)
Components of a namespace can be imported with <import "<namespace>">.
Circular imports are to be aborted. Missing components, depending on preference, should either deliver a fallback (For example: plaintext, an error component, ...), or throw an error.
- To make a component accessible without import, you can use the global namespace:
<namespace global>. - To return to components only being accessible within the layout itself, you can change to the local namespace:
<namespace local>.
Note: Changing a namespace is not retroactive. All components in the layout prior to the namespace instruction tag will stay in their current namespace.
In XML:
<import "namespace">→<import name="namespace"/><namespace "namespace">→<namespace name="namespace"/><namespace global>→<namespace-global/><namespace local>→<namespace-local/>- See the Extended Attribute format.
Variables, insertion, function calls, operators, ...
Intact has a "context" in which variables are stored. These can be accessed, assigned to, and inserted in places. They can either be a value or a callable function. The result of a function can be used as a value.
Setting the value of a variable
You set variables using the <set ...> object. A variable is set to the value of an attribute with the matching name (e.g.: <set my_variable="example value">).
Use type annotation to set values with types other than strings.
Multiple variables are allowed per <set> object, provided there are no duplicate attribute names.
In XML:
<set ... >→<set ... />- See the Extended Attribute format.
Inserting a variable as an object
<:variable_name>for inserting values and the results of function calls that don't take any arguments.<:function_name "argument" var_arg arg="value">for calling functions that take arguments. The attribute values will be converted into the proper type.
In XML:
<:variable_name>→<value name="variable_name"/><:function_name "argument" var_arg arg="value">→<call name="function_name" with=""argument" var_arg arg="value""/>
Inserting in an attribute and most other places where variables are supported
Variables are inserted with: attribute=variable (no quotes).
It's not really much more complicated than that.
For inserting the value of function calls with arguments, conditions, and ternary operators, you need to use square brackets to encase the statements:
<Example width=[getSize "height"] visible=[disabled ? "false" : "true"]>
<set gotANat20=[[randomRoll 1 20] == 20]>
These can be nested.
In XML: See the Extended Attribute format.
Operators
Values that are numerical can be added +, subtracted +, multiplied *, and divided / with each other.
This applies in most places where you can use values and variables.
Examples:
size=input*2width=128-4<if variable-1 == 2><for i in [range 1 [length items]+1]>*
* range and length in this example are external functions and not part of the Intact specification.
Exponentiation **, floor devision //, and modulo % are also possible.
In XML: See the Extended Attribute format.
String Joining
You can join strings in attributes in two ways:
attribute = "Hello"+"World": concatenate two values (e.g.:"Hello"+"World"→"HelloWorld")attribute = "Hello".."World": join with a space if the other value has content (e.g.:"Hello".."World"→"Hello World","Hello"..""→"Hello")
If other types of values are joined with a string, they should be converted into one.
In XML: See the Extended Attribute format.
Brackets
You can use brackets. This applies in most places where you can use values and variables.
In XML: See the Extended Attribute format.
Indexing
With an index number:
list.<n>: item at index (e.g.: <:list.0> (first item), <:list.-1> (last item))list.<n>:<m>: range of items
With a key:
table.<key>: item with given key
If Statements
If statements add their children to the tree if a condition is met.
<if condition>
...
</if>
As an alias, <? ...> ... </?> can also be used.
Examples:
<if updateAvailable> There is a new update available. </if><? updateAvailable> There is a new update available. </?>
To add an else case, add the <else> or <:> element to the <if> object's tree as a divider.
In example:
<if updateAvailable>
There is a new update available.
<else>
You are up-to-date.
</if>
<? updateAvailable>
Update available!
<:>
Up-to-date.
</?>
Conditions
==: equal to!=: not equal to<,>: less than, more than<=,>=: less than or equal to, more than or equal toin: value is in other value
Example: <if 9 + input == 21>
Locical Operators:
&&orand: true if conditions on both sides are met||oror: true if a condition on either side is met!ornot: prefix to invert value
Example: <if 9 + input == 21 and valid or skipped>
"Ternary" Operators
A ternary operator is a conditional operator that takes a condition, a value to be returned if the condition is true, and a value to be returned if the condition is false. - GeeksforGeeks
This definition is a bit loose in Intact, since these "ternary" operators have a default false return value of an empty string "",
meaning you dont have to provide an else value if it fits for the value type.
<condition ? value><condition ? value : else-value>
In XML:
<9 + input == 21 ? "Correct!" : false_message>→<ternary condition="9 + input == 21" true="Correct!" false="\ex-attr\.false_message"/>- See the Extended Attribute format.
Ternary operators can also be used in an attribute and other places.
For Loops
You can iterate over indexable types. You can access the item in a loop like variables.
<for item in items>
<:item> // (example)
</for>
A shorthand form also exists, but it might not be for everyone: <~ item : items> <:item> /* (example) */ </~>
In XML:
<for iteration_item_name in [getList "listID"]>(example) →<for item="iteration_item_name" in="\ex-attr\.[getList "listID"]">- See the Extended Attribute format.
Extended Attribute Format
Since Intact is really stretching the concept of what XML attributes are capable of, there has to be a custom format for attributes. The string consists of multiple parts in the following order:
\ex-attr\: marks this as an extended attribute (required)?: if this attribute is optional (only for components)!<type>: attribute type.<value>: escaped attribute value
If you implemented it right, the following attributes should result in these strings:
attr1="some string"→attr1="some string"(no change since no extended attribute features were used)attr2?→\ex-attr\?attr3?="double optional"→\ex-attr\?."double optional"attr4:integer="60"→\ex-attr\!integer."60"attr5:integer→\ex-attr\!integerattr6="always"..[case ? "sometimes"]→\ex-attr\."always"..[case ? "sometimes"]attr7=variable→\ex-attr\.variable- You get the idea.