PhiML Specification

© 2007 James Laver, Adrien Howard

Abstract:

PhiML is a markup language designed to simplify and to eliminate unnecessary distinctions between metadata and data.


Definitions:

Content:

Content refers to either a quoted string or a bare word. (See below)


Quoted Strings:

Quoted Strings are a type of content that start with a quotation mark ( ' , “ , or ` ) , hold content and end with the same quotation mark they began with.


Bare-Words:

Bare-words are a type of content made of characters(a word) unenclosed in quotations. It is impossible for a bare-word to contain a space. Bare-words separated by a space only make additional bare-words. Additionally, bare-words must conform to the character restrictions below:

Character Restrictions to Bare-Words:

   1.

      May not contain parentheses or square brackets ( (), [] )
   2.

      May not contain and kind of quotation marks ( ',”,` )


Tags:

A tag is a data structure in which to house data. All tags have a left parenthesis “(“ a bare-word “tagname” representing a tag name, optional content(barewords, quoted strings, tags) and a right parenthesis “)”.


Sub Tag:

A sub tag is a tag within a tag. All Tags within a Document are technically Sub Tags except for the root tag, which is the document itself. Tags inside tags give PhiML documents additional structure.


List:

A list is a special data structure made of a left square bracket “[“ then a series of space delimited bare- words or quoted strings and a right square bracket “]”. It creates a series of implied tags each having only a single subtag or attribute.


Document:

A document is a collection of tags bound together by a transparent root Document tag. In PhiML, there is no need for a “root node” as the document iteself acts as the root. A document may or may not refer to a file.


Optional Directives:

Throughout the course and evolution of PhiML development, there will be the development of optional directive tags. These tags will be marked with an exclamation point at the beginning of the tag and given special words to define what they do to the output of the document. For example (!encoding “utf32”) makes the encoded output of the document utf32. The parser will look for directive tags until it encounters a non- directive tag.

Current directives are !encoding.


Document Structure:

The structure of any document is largely ambiguous, however the basic document structure is

Optional Directives, highest level tags, their data/tags, etc. Here is an example structure:

(!encoding “utf32”)

(family

  (parents [“Father” `Mother`]

    (children [Son “Daughter”]

      (pets [Rosco Rattail]))))

Document Validity:

The document is said to be valid if:

   1.

      All tags begin with a left parenthesis “(“ and a bare-word “tagname” and end with a right parenthesis “)”.
          *

            Good Examples:
                o

                  (tagname)
          *

            Bad Examples:
                o

                  (bad-tag
                o

                  ()
                o

                  bad-tag)
   2.

      All Quoted strings begin and end with the same quotation mark ( ", ', ` ). A string will not be considered terminated until a matching quotation mark is encountered. Quotation marks within strings can be escaped by doubling up, eg. "He said, ""test""." would be read in as: He said, "test".
          *

            Good Examples:
                o

                  “Some content”
                o

                  'Some content'
                o

                  `Some content`
          *

            Bad Examples
                o

                  “Bad String'
                o

                  `Bad String”
                o

                  'Bad String`
                o

                  Bad String”
   3.

      All barewords conform to character restrictions placed on them in the Bare-Words section above.
          *

            Good Examples:
                o

                  Valid-bare-word
          *

            Bad Examples:
                o

                  invalid-(bare-word
                o

                  invalid-”bare-word”


Recommended Practices:

Although it is syntactically valid, it's recommended that all strings and bare-words inside a tag precede any sub tags or lists in that tag. The reason: It keeps the markup clean looking. For example:

(tag bare-word(subtag))

Looks much more aesthetically pleasing than:

(tag (subtag)bare-word)

In more complex tags, the former may be much more readable than the latter.