Compound Fields
***************

class DateYYYYMMDD(value=Unspecified, **kw)

   Bases: "flatland.schema.compound.Compound",
   "flatland.schema.scalars.Date"

   compose()

      Return a text, native tuple built from children’s state.

      Returns:
         a 2-tuple of text representation, native value. These
         correspond to the "serialize_element()" and "adapt_element()"
         methods of "Scalar" objects.

      For example, a compound date field may return a ‘-‘ delimited
      string of year, month and day digits and a "datetime.date".

   explode(value)

      Given a compound value, assign values to children.

      Parameters:
         **value** – a value to be adapted and exploded

      For example, a compound date field may read attributes from a
      "datetime.date" value and "set()" them on child fields.

      The decision to perform type checking on *value* is completely
      up to you and you may find you want different rules for
      different compound types.

class JoinedString(value=Unspecified, **kw)

   Bases: "flatland.schema.containers.Array",
   "flatland.schema.scalars.String"

   A sequence container that acts like a compounded string such as
   CSV.

   Marshals child element values to and from a single string:

      >>> from flatland import JoinedString
      >>> el = JoinedString(['x', 'y', 'z'])
      >>> el.value
      u'x,y,z'
      >>> el2 = JoinedString('foo,bar')
      >>> el2[1].value
      u'bar'
      >>> el2.value
      u'foo,bar'

   Only the joined representation is considered when flattening or
   restoring with "set_flat()".  JoinedStrings run validation after
   their children.

   separator = u','

      The string used to join children’s "u" representations.  Will
      also be used to split incoming strings, unless "separator_regex"
      is also defined.

   separator_regex = None

      Optional, a regular expression, used preferentially to split an
      incoming separated value into components.  Used in combination
      with "separator", a permissive parsing policy can be combined
      with a normalized representation, e.g.:

         >>> import re
         >>> schema = JoinedString.using(separator=', ',
         ...                             separator_regex=re.compile('\s*,\s*'))
         ...
         >>> schema('a  ,  b,c,d').value
         u'a, b, c, d'

   member_schema

      alias of "flatland.schema.scalars.String"

   set(value)

      Assign the native and Unicode value.

      Attempts to adapt the given *iterable* and assigns this
      element’s "value" and "u" attributes in tandem.  Returns True if
      the adaptation was successful.  See "Element.set()".

      Set must be supplied a Python sequence or iterable:

         >>> from flatland import Integer, List
         >>> Numbers = List.of(Integer)
         >>> nums = Numbers()
         >>> nums.set([1, 2, 3, 4])
         True
         >>> nums.value
         [1, 2, 3, 4]

   value

      A read-only "separator"-joined string of child values.

   u

      A read-only "separator"-joined string of child values.
