NBML: Not Bunk Markup Language

Update: 2008 - When this post was written, we had no idea that a similar project named YAML (Yet Another Markup Language), was also happening on another corner of the internet. We both had similar goals, and independently came to a pretty similar syntax. YAML is getting traction, so go with that one!

(Okay the name might change)

How long have we been staring at screens full of XML and not complaining? Have a look at a typical chunk of XML - it’s all noise. Quotes and angled brackets and slashes and more quotes and closing tags. It’s not exactly the easiest thing in the world to read. Our eyes have become accustomed to it because we’ve been looking at it for so long (and HTML/SGML before XML).

I was thinking about my recent rant about how unreadable XML is. So we (myself and some colleagues) came up with an alternate syntax. I collated a selection of everyday XML that we have to deal with, including some Ant files, Jelly scripts, J2EE config files and acceptance tests, and we tried to express them in a simple form that was, above all, readable.

Initially we went down the C like syntax route of curly braces and semi-colons and stuff. This was quite concise and looked like a hybrid of JavaScript and CSS which we quite liked. That was until Chris Stevenson brought up the idea of using Python style formatting where blocks are delimited by indentation. I particularly like this style because we all indent blocks properly anyway (if you don’t you’re a sick person) for the sake of human readability - the extra identifier (close curly, close tag, whatever) is only there to keep the parser/compiler happy.

So, here’s what we ended up with

Original XML

<project name="MyProject" default="dist" basedir=".">
  <description>
    simple example build file
  </description>
  <!-- set global properties for this build -->
  <property name="src" location="src"/>
  <property name="build" location="build"/>
  <property name="dist"  location="dist"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
    <!-- Create the build directory structure used by compile -->
    <mkdir dir="${build}"/>
  </target>

  <target name="compile" depends="init"
        description="compile the source " >
    <!-- Compile the java code from ${src} into ${build} -->
    <javac srcdir="${src}" destdir="${build}"/>
  </target>

  <target name="dist" depends="compile"
        description="generate the distribution" >
    <!-- Create the distribution directory -->
    <mkdir dir="${dist}/lib"/>
    <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
  </target>

  <target name="clean"
        description="clean up" >
    <!-- Delete the ${build} and ${dist} directory trees -->
    <delete dir="${build}"/>
    <delete dir="${dist}"/>
  </target>
</project>

NBML equivalent

project name:MyProject default:dist basedir:.
  description [simple example build file]
  # set global properties for this build
  property name:src   location:src
  property name:build location:build
  property name:dist  location:dist

  target name:init
    # Create the time stamp
    tstamp
    # Create the build directory structure used by compile
    mkdir dir:${build}

  target name:compile depends:init description:[compile the source]
    # Compile the java code from ${src} into ${build}
    javac srcdir:${src} destdir:${build}

  target name:dist depends:compile description:[generate the distribution]
    # Create the distribution directory
    mkdir dir:${dist}/lib
    # Put everything in ${build} into the MyProject-${DSTAMP}.jar file
    jar jarfile:${dist}/lib/MyProject-${DSTAMP}.jar basedir:${build}

  target name:clean description:[clean up]
    # Delete the ${build} and ${dist} directory trees
    delete dir:${build}
    delete dir:${dist}

Initial opinion of this is yeuuurgh. But try staring at it for a while, it gets nicer and nicer and certainly is less of a headache to read. It’s not for everyone, but so far most people have liked it.

So what makes it more readable?

All the angle brakets junk has been removed.
Correct indentation is forced.
There is no need for closing elements as the indentation expresses when a block ends.
Attributes are specied as a:b instead of a="b".
Element text is specified as echo hello instead of <echo>hello</echo>.
If a text node or attribute contains whitespace chars it is enclosed in square brackets like echo [hello world].
Namespaces are expressed like xsl.template.
Comments are on lines starting with #.

Although the syntax is different the structure it represents is the same as that of XML.

Here’s the nice part. NBML includes a SAX compliant parser, so any existing XML enabled applications can be switched to NBML just by modifiying a system property. So you can use tools like Ant, Jelly, DOM, Xalan on NBML painlessly and all the existing millions of XML specs (XSL, Schema, XPath, XInclude, SOAP, XQL, ….) still apply.