Candle Markup Reference

1. Introduction

• Whitespace is non-ambiguous: in XML, the whitespaces between the elements can be ambiguous as whether they are text nodes or just pure formatting whitespaces that can be ignored. Thus special processing rules are defined in XSLT and XQuery to tackle this problem. But these rules only partially solve the problem, and they make XML parsing and processing complicated. Candle requires text nodes to be explicitly quoted, thus cleanly solves the problem.
• Literal values are strongly-typed: literal values in Candle have unique syntax to identify its type, thus making Candle Markup a strongly-typed format, whereas XML is only semi-typed without schema.
• Namespace handling is much cleaner: namespaces in Candle use a hierarchical syntax like Java, and can be fully expanded without using the prefix syntax.
• Candle Markup is a strict subset of Candle Script: any Candle Markup can be directly cut and pasted into Candle script (as long as the namespace declarations are the same); whereas XML markup must be carefully examined before being pasted into XQuery as literal markup as special characters like '{' and '}' may need to be escaped.
• Cleaner data model: Candle gets rid of some of the legacy features of XML, like DTD and processing instruction; namespaces in Candle are treated as lexical information rather than nodes in the data model. You can refer to Candle Data Model for more details.
• More powerful data model: attributes are more equal to elements in Candle; they can hold a list of atomic values or even complex element as content.
• Unified with OOP object data model: Candle unifies the markup data model in XML with the object data model in OOP languages.

2. Namespace Declaration

• If a name does not have any prefix, then it is resolved under the declared default namespace. If there's no default namespace declaration, then it is consider to be under the nil namespace. So in the above example, names foo, bar, M, L, Z are all under namespace ns:default:name:space;
• If the name starts with top-level name ns, then it is a fully expanded Qname, like the qux in the above example;
• Otherwise, the name is a prefixed name, and the first name should be one of the prefixes declared at the beginning of the document, except predefined prefixes (nil and candle).The baz, d and foe in the above example are prefixed names. The name baz is using predefined prefix nil.

• The last name maps to the local name in XML;
• Other names before the last name are mapped into XML namespace URI;

• ns: reserved for fully expanded namespace;
• nil: predefined prefix for the empty namespace;
• candle: predefined prefix for ns:org:candlescript.

• Unlike XML, that allows namespace declaration at node level, Candle namespace can only be declared at the beginning of the document. This make is easier for both Candle processors and users, as there's only one place to look for namespace declaration in a document, and a prefix always refer to the same namespace in a document.
• Candle introduces the hierarchical namespace syntax, which is much cleaner than the URI syntax in XML;
• Attribute names without prefix are resolved under the default markup namespace instead of the empty namespace. This makes name resolution more consistent across all kind of names.
• Besides the name characters defined in XML, Candle also introduces a name character escape mechanism. The syntax is the same as URI escape syntax. This allows the actual value of the Candle name to contain any special character. However, if a markup document needs to be exported into XML, then such special characters in the name should be avoided. This syntax is provided to support special non-XML names, like key name in JSON, filenames in native operating system, SQL DB table and column names.

3. Literal Value

• Long integer: -12345L
• Double inifinity and NaN: +infinity, -infinity, nan;
• Measure: 10pt, .8em
• Percentage: 50%
• Local datetime: !2011-05-13t15:01:00!
• GMT datetime: !2011-05-13t15:01:00z!
• Year: !2012y!
• Color: #ff00cc
• Qualified name as literal value: bold
• Binary date encoded in Base64 notation: !12ab 56ef!

Named Character Entities

• those predefined in XML: " & ' < >
• those predefined in HTML: HTML character entities
• those predefined by Candle:
• &tb;        - horizontal tab, ASCII code 9
• &lf;        - line feed or new line character, ASCII code 10
• &cr;        - carriage return, ASCII code 13
• &dq;        - double quote, ASCII code 34

4. Text, Data and Comment Node

Text Node

Data Node

Comment Node

5. Element and Attribute Node

• Literal value as attribute and element content does need to quoted;
• Attribute and element has been extended to support a list of atomic values, or even complex content like element and object;

Array as Attribute Value

ID Attribute and ID Shorthand

6. Object Notation

Customer {
 firstName = "John"
 lastName = "Doe"
 phoneNum = "9555-0101"
 address = Address {
 street = "1 Main Street"
 city = "Santa Clara"
 state = "CA"
 zip = "95050"
 }
 "a text node"
}

<Customer
 firstName = "John"
 lastName = "Doe"
 phoneNum = "9555-0101"
 address = <Address
 street = "1 Main Street"
 city = "Santa Clara"
 state = "CA"
 zip = "95050" />
 >
 "a text node"
</Customer>

Customer {
 firstName: "John";
 lastName: "Doe";
 phoneNum: "9555-0101";
 address: Address {
 street: "1 Main Street";
 city: "Santa Clara";
 state: "CA";
 zip: "95050";
 }
 /* text node not supported*/
}

Complex Attribute Content

• SVG path in XML syntax:
• <path d="M 100,50 L 75,110 C 123,256 23,278 245,290 Z" />
• SVG path in Candle syntax: 
• <path d=(M, 100,50, L, 75,110, C, 123,256,23,278,245,290, Z) />
or as element content
  <path> M 100 50 L 75 110 C 123 256 23 278 245 290 Z </path> (this element syntax is just for illustration purpose, not actually used in Candle Style markup)
• CSS style in XML syntax:

• <div style="width:56; padding:1 1 2 2; border-width:1;
     border-color:#fff #fff #999 #999; border-style:solid;" />
• CSS style in Candle syntax:

• <div style={width=56 padding=(1,1,2,2) border-width=1
     border-color=(c:'fff',c:'fff',c:'999',c:'999') border-style=solid} />

Anonymous Object

Unified Data Model

7. Markup Document

8. Summary

Appendices

A. References

• General markup references:
• XML 1.0;
• Namespaces in XML 1.0;
• HTML5 Syntax;
• MicroXML;

• Data type references:
• XML Schema Data Types;
• CSS syntax and basic data types;
• SMIL time and duration;
• ISO 8601 date, time and duration;

• Object notation references:
• JSON;
• JavaFX literal object syntax;
• YAML;
• Turtle - Terse RDF Triple Language;
• Groovy Markup;
• Scene description languages;

B. Candle Markup vs. MicroXML

• Encoding. UTF-8 only.
• Processing instructions. Not allowed.
• DOCTYPE declaration. Clearly the internal subset should not be allowed.

• Namespace simplification;
• Whitespace non-ambiguity;
• Strongly-type literal values;
• Extended attribute and element data model;
• Unification with JSON and object data model;

C. Candle Markup vs. HTML5

• Candle Markup is a general format: whereas HTML is a domain-specific format. Parsing of Candle Markup only depends on the grammar, not the element schema.
• Namespace support: the HTML syntax of HTML5 does not support namespace, thus limiting its ability to embed micro-formats, meta-data, etc.
• Whitespace is ambiguous in HTML: while this might not be a problem for applications displaying HTML, it can be a problem for applications that generates HTML dynamically.
• Extended attribute content model: attributes in Candle Markup can hold list of atomic values and even element as content, making it convenient to represent data like SVG path, CSS inline style as structured data instead of strings in abstract or domain-specific syntax. Actually, all static data in HTML5, excluding embedded client-side scripts, can be directly supported in Candle without using abstract syntax.

D. Candle Markup vs. JSON

• Candle objects are always named. This qualified name provides important annotation to the data contained in the object. This can be important for data formality and longevity. In JSON, the object name is anonymous, or has to be encoded as key name.
• Candle objects have built-in support of mixed content. JSON is not.
• Candle objects supports more literal value types than JSON. Important literal value types, like datetime, Qname and URI, are not supported by JSON.
• Candle has advanced processing features (like grammar, schema, path, query, transformation, update) well-defined. JSON depends on the hosting language to further process it.
• Candle Object Notation is less verbose than JSON: JSON requires object key name to be double quoted and object values to be delimited by ',', Candle does not;

E. Candle Markup vs. YAML

• Embedded as structured data instead of quoted text: Candle Markup can be embedded in existing scripts as structured data, instead of as quoted text like YAML. If a language already supports directly embedded XML, then it should not be hard to extend such language to support Candle Markup, as Candle Markup's syntax is similar to XML. Embedding as structured data instead of quoted text enjoys better IDE support, like syntax check and highlighting, content assistant, auto indentation and formatting, etc.
• Namespace support: All names are namespaced in Candle Markup. But only the type annotation tag names are namespaced in YAML, key names in maps are not namespaced.
• More literal data type: Candle Markup supports more built-in literal data types than YAML, like datetime, Qname, uri. YAML will need to use type annotations for these literal types.
• Mixed text content support: YAML is not designed for mixed text content usage.
• Advanced processing: Candle is a general-purpose programming language, and has whole stack of advanced processing features (like grammar, schema, path, query, transformation, update) defined on top of the markup data. Whereas YAML is only a data format and would required to be transformed into other data models to be further processed.

F. Candle Markup vs. Several Alternatives

G. A List of Candle Markup Examples