devguide pluginbasic yamlprimer

MDG: a YAML Primer for Melody Developers

The Melody registry is expressed using a simple syntax known as YAML. Before we introduce you to YAML and give you enough of a grasp of its fundamentals to use this manual, please understand that there are many more useful and more detailed guides to YAML on the Internet if you wish to further your understanding and appreciation this alternative markup language.

About YAML

YAML was developed by engineers who needed to create simple hierarchical documents, but were tired of the verbosity of XML. In fact, YAML does virtually all that XML, in its basic form, was designed to do, but does it in a way that is easier to read and faster to type. Therefore, if you have a basic understanding of XML, you will come up to speed on YAML in no time. Take a look at these two examples, one in XML and the other YAML:

XML

<?xml version="1.0">
<address>
    <first_name>Byrne</first_name>
    <last_name>Reese</last_name>
    <email>byrne@majordojo.com</email>
    <company>
        <name>Six Apart, Ltd.</name>
        <street_address>
          548 4th Street, San Francisco, CA 94107
        </street_address>
    </company>
</address>

YAML

address:
    first_name: Byrne
    last_name: Reese
    email: byrne@majordojo.com
    company:
        name: Six Apart, Ltd.
        street_address: 548 4th Street, San Francisco, CA 94107

Aaahhh, its like a breath of fresh air.

Ok, that is not entirely fair, as XML is a very powerful markup language capable of expressing extraordinarily complex data types. However, for simple structures, YAML is much simpler -- which makes it the perfect syntax for Melody's registry.

Author's Note: Technically, the designers of YAML made it possible to do everything you can do in XML in YAML. However, Melody's YAML parser does not support the full YAML specification - just the minimal subset to keep this simple and fast.

Basic YAML Data Structures

Here are some different ways to represent common data structures in YAML:

Arrays

i_am_an_array:
    - value1
    - value2
    - value3

Hashes

i_am_a_hash:
    key1: value1
    key2: value2
    key3: value3

Common YAML Pitfalls

Ok, we all love YAML. Yay, YAML! But to be fair it is not without its imperfections. One things developers will often note is that it is very picky with regards to its syntax. For example, it tends not to like tabs, preferring spaces instead. And just like Python it is rather draconian in its requirements with regards to things being spaced evenly and consistently.

So if you get a weird YAML parsing error, it might be because of spaces, or tabs.

Oh yeah, and all YAML files must end with at least one full, complete blank line. Don't forget.

Continue Reading

• MDG: Building Your First Melody Plugin

 

      [[http://openmelody.org/assets_c/2009/06/melody-logo-mark-on-white-thumb-150x150-7.jpg|float|align=left]] 

Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

• Author: Byrne Reese
• Edited by: Violet Bliss Dietz