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

class 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 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

      The default child type is "String", but can be customized with
      "Integer" or any other type.

      alias of "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.
