Syntax

philcali edited this page Jul 5, 2012 · 8 revisions

There are not many syntax rules, and the parsing engine is pretty flexible. Here is a quick bullet list of the syntax rules, and a following in-depth explanation of each:

  • Whitespace is important
  • JSON-style attributes
  • Id attributes prefixed with "#"
  • Class attributes prefixed with "."
  • Attribute shorthand with "@" prefix
  • Unescaped text is suffixed with is unescaped
  • Markdown indirect link style templates
  • Indirect definitions are delimited from main document by ---
  • Comments are represented by //

Whitespace is Important

The parser uses whitespace to determine if the next node is a child or sibling.

I think it is better to explain the difference by actually looking at some real markup.

html
  head title "Blah"
  body

In this case, head and body are both children of html, and their same level of indention also states that they are siblings.

<html>
  <head>
    <title>Blah</title>
  </head>
  <body/>
</html>

The children of head were written on the same line, and this is where the parser is flexible. Nodes written in this manner are treated as recursive children.

Note: Nodes written on the same line like that, is the Quick and Dirty way of writing LMXML. Use this method if you know for sure that there will be no siblings.

Nodes

A node is a word consisting of numbers, letters, hyphens, or underscores. A node can have an infinite number of children and siblings.

lmxml is a pretty cool guy

lmxml
  is
  a
  pretty cool guy
<lmxml>
  <is>
    <a>
      <pretty>
        <cool>
          <guy></guy>
        </cool>
      </pretty>
    </a>
  </is>
</lmxml>
<lmxml>
  <is></is>
  <a></a>
  <pretty>
    <cool>
      <guy></guy>
    </cool>
  </pretty>
</lmxml>

Arbitrary Text

Text is wrapped in quotes. Multi-line text is fenced in with ~~~.

lmxml is "wonderful"

lmxml
  ~~~
is wonderful, ya?
and this, and that
  ~~~
<lmxml>
  <is>wonderful</is>
</lmxml>

<lmxml>is wonderful, ya? and this, and that </lmxml>

Note: Before the markdown module was added, multi-line text was required to be fenced in by ```. This method will still work if you have LMXML already written this way, but it's advised to switch over to the new way, as this method has been deprecated since v0.1.2.

JSON-style Attributes

Assigning meta data to nodes can be done like writing JSON.

people
  person { name: "Philip Cali" }
  person { name: "Blue Steel" }

The same rules apply for JSON keys as they do for nodes: letters and numbers are excepted, as well as hyphens and underscores.

<people>
  <person name = "Philip Cali"></person>
  <person name = "Blue Steel"></person>
</people>

Id Attributes

Special syntax was given to id's and classes because they are so commonly written in HTML.

users
  user #1 name "Philip Cali"
  user #2 name "Blue Steel"
<users>
  <user id = "1">
    <name>Philip Cali</name>
  </user>
  <user id = "2">
    <name>Blue Steel</name>
  </user>
</users>

Class Attributes

body
  div #page
    div .header .wide h1 "Great Jarb!"
<body>
  <div id = "page">
    <div class = "header wide">
      <h1>Great Jarb!</h1>
    </div>
  </div>
</body>

Shorthand Attributes

As one might say the JSON attributes are the long hand, "@" attributes are the shorthand. It is important to note that these attributes do not require a value. If no value is given, the value is assumed to be the attribute key. This is useful for inputs that need to be marked CHECKED, for example.

form @method = "POST"
  input @type = "text" @name = "username"
  input @type = "password" @name = "password"
  input @type = "checkbox" @checked @name = "remember"
<form method = "POST">
  <input type = "text" name = "username"/>
  <input type = "password" name = "password"/>
  <input type = "checkbox" checked = "checked" name = "remember"/>
</form>

Unescaped Text

When writing HTML, you may find yourself required to write harmful characters or even special tags (namely the CDATA).

In such a case, you are required to append is unescaped to the specified text.

"<!DOCTYPE html>" is unescaped

html
  head title "Page"
  body div #page h1 "Leave me alone!"
<!DOCTYPE html>
<html>
  <head>
    <title>Page</title>
  </head>
  <body>
    <div id = "page">
      <h1>Leave me alone!</h1>
    </div>
  </body>
</html>

Node Templates

While LMXML is a short hand for writing XML, even that can lead to lots of tabbing.

You can create labels that expand into more nodes, to save some indention. This syntax is borrowed from Markdown style Indirect links.

They called templates because they can used multiple times

html
  head
    [styles]
    [scripts]
  body
    div #page
      div #header h1 "Hey there!"
      div .contents [contents]
      div #footer p "&copy; Philip Cali" is unescaped
---
[styles]: link @rel = "stylesheet" @type = "text/css" @href = "main.css"

[scripts]:
  script @type = "text/javascript" @src = "/jquery.js"
  script @type = "text/javascript" ```
$(document).ready(function() {
  alert("We did it!");
});
    ``` is unescaped

[contents]: p "contents go here"
<html>
  <head>
    <link rel = "stylesheet" type = "text/css" href = "main.css"/>
    <script type = "text/javascript" src = "/jquery.js"></script>
    <script type = "text/javascript">
$(document).ready(function() {
  alert("We did it!");
});
    </script>
  </head>
  <body>
    <div id = "page">
      <div id = "header">
        <h1>Hey there!</h1>
      </div>
      <div class = "contents">
        <p>contents go here</p>
      </div>
      <div id = "footer">
        <p>&copy; Philip Cali</p>
      </div>
    </div>
  </body>
</html>