root/trunk/spec/set.dbk

<?xml version="1.0"?>
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article>
  <articleinfo>
    <title>
      Set Language-Independent Type for
      <trademark>YAML</trademark>&nbsp;Version&nbsp;1.1
    </title>

    <subtitle>
      Working Draft 2005-01-18
    </subtitle>

    <authorgroup>
      <author>
        <firstname>Oren</firstname>
        <surname>Ben-Kiki</surname>
        <email>oren@ben-kiki.org</email>
      </author>

      <author>
        <firstname>Clark</firstname>
        <surname>Evans</surname>
        <email>cce+yaml@clarkevans.com</email>
      </author>

      <author>
        <firstname>Brian</firstname>
        <surname>Ingerson</surname>
        <email>ingy@ttul.org</email>
      </author>
    </authorgroup>

    <copyright>
      <year>2001-2005</year>
      <holder>Oren Ben-Kiki<fo>,&nbsp;</fo></holder>
      <holder>Clark Evans<fo>,&nbsp;</fo></holder>
      <holder>Brian Ingerson</holder>
    </copyright>

    <legalnotice>
      This document may be freely copied provided it is not modified.
    </legalnotice>

    <abstract>
      <title>Status</title>

      <para>
       This specification is a draft reflecting consensus reached by members of
       the <ulink
       url="http://lists.sourceforge.net/lists/listinfo/yaml-core">yaml-core
       mailing list</ulink>. Any questions regarding this draft should be
       raised on this list.
      </para>
    </abstract>
  </articleinfo>

  <section>
    <variablelist>
      <varlistentry>
        <term>
          <para>
            URI:
          </para>
        </term>

        <listitem>
          <para>
            <userinput>tag:yaml.org,2002:set</userinput>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Shorthand:
          </para>
        </term>

        <listitem>
          <para>
            <userinput>!!set</userinput>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Kind:
          </para>
        </term>

        <listitem>
          <para>
            Mapping.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Definition:
          </para>
        </term>

        <listitem>
          <para>
            Unordered set of non-equal values.
          </para>

          <para>
            A set is an unordered collection of nodes such that no two nodes
            are equal. While sets are a fundamental mathematical type, YAML
            only supports them as the domains of a mapping. Hence the YAML
            syntax for a set is a mapping with all-null values.
          </para>

          <para>
            Most programming languages do not have a built-in native data type
            for supporting sets. Such data types are usually provided by
            libraries. If no such data type is available, an application may
            resort to loading a <quote><userinput>!!set</userinput></quote>
            into a native hash table where all values are null.
          </para>

          <para>
            The <quote><userinput>!!set</userinput></quote> tag may be given
            explicitly. Alternatively, the application may choose to implicitly
            type mappings with all-null values to sets. In this case, an
            explicit <quote><userinput>!!map</userinput></quote> transfer must
            be given to mappings that have all-null values but do not represent
            sets.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <example>
      <title><userinput>!!set</userinput> Examples</title>
<programlisting>
# Explicitly typed set.
baseball players: !!set
  ? Mark McGwire
  ? Sammy Sosa
  ? Ken Griffey
# Flow style
baseball teams: !!set { Boston Red Sox, Detroit Tigers, New York Yankees }
</programlisting>
    </example>
  </section>
</article>