man(1) Manual page archive


     FORMAT(2)                                               FORMAT(2)

     NAME
          format - structured data interchange

     SYNOPSIS
          include "sys.m";
          include "bufio.m";
          include "sexprs.m";
          include "format.m";
          format := load Format Format->PATH;

          Fmtspec: adt {
               name:   string;
               fields: cyclic array of Fmtspec;
          };
          Fmt: adt {
               kind:   int;
               fields: cyclic array of Fmt;
          };
          Fmtval: adt {
               text:   fn(v: self Fmtval): string;
               val:    ref Sexprs->Sexp;
               recs:   cyclic array of array of Fmtval;
          };
          Fmtfile: adt {
               spec:   array of Fmtspec;
               descr:  array of byte;

               new:    fn(spec: array of Fmtspec): Fmtfile;
               open:   fn(f: self Fmtfile, name: string):
                         ref Bufio->Iobuf;
               read:   fn(f: self Fmtfile, iob: ref Bufio->Iobuf):
                         (array of Fmtval, string);
          };
          init:     fn();
          spec2se:  fn(spec: array of Fmtspec): list of ref Sexprs->Sexp;
          spec2fmt: fn(spec: array of Fmtspec): array of Fmt;
          se2fmt:   fn(spec: array of Fmtspec, se: ref Sexprs->Sexp):
                       (array of Fmt, string);
          rec2val:  fn(spec: array of Fmtspec, rec: ref Sexprs->Sexp):
                       (array of Fmtval, string);

     DESCRIPTION
          Format provides support for programs that wish to marshal
          and unmarshal structured data. It is designed to enable a
          client to request that the structure data is provided by the
          server in a particular format, and for the server to be able
          to check that it is capable of providing that format.

          A record consists of a set of fields, each represented by
          one element in an sexprs(2) list. The content of a field can

     FORMAT(2)                                               FORMAT(2)

          be a simple value, or it can hold a list containing any num-
          ber of sub-records, each holding a set of fields, recur-
          sively defined as above.

          The Fmtspec type defines the format for a field in a record.
          Name gives the name of the field, and fields gives the
          structure of the fields in any sub-records it contains (for
          a field with a simple value, this will be nil).  Thus an
          array of Fmtspec values can define the structure of all the
          fields in a record.  Here is an example structure specifica-
          tion:

               Name, Address, Phone: con iota;
               Number, Kind: con iota;
               spec := array[] of {
                    Address => Fmtspec("address", nil),
                    Name => Fmtspec("name", nil),
                    Phone => Fmtspec("phone", array[] of {
                         Kind => Fmtspec("kind", nil),
                         Number => Fmtspec("number", nil),
                    }),
               };

          By placing each field in the structure specification at a
          known index, a link is made from the symbolic constants in
          the program to the textual field names.

          A structure specification may also be represented by a list
          of S-expressions, where each member of the list names a
          field in the structure. If a member is itself a list, it
          specifies a field containing sub-records: its first member
          gives the name of the field, and subsequent members specify
          the fields in its sub-records.  For example, the above spec-
          ification could be written as the S-expression:

               (name address (phone number kind))

          The Fmt type also defines a record structure, but with
          respect to an existing Fmtspec structure specification.  An
          Fmt value represents a field, and kind holds the index of
          that field in the original structure specification.

          Se2fmt converts from an S-expression list, se (a structure
          specification), to a set of Fmt values.  The specification
          must be a subset of spec; i.e. each field in se must exist
          in spec. Se2fmt returns a tuple (f, err).  If the specifica-
          tion is bad, f will be nil, and err describes the error.
          Otherwise, each member of f gives a field specified by se.
          For example, given the above structure definition, after
          executing:

                    se := Sexp.parse("(address (phone number))").t0;

     FORMAT(2)                                               FORMAT(2)

                    (f, err) := se2fmt(spec, se);

          f[0].kind will hold the symbolic constant Address, and
          f[1].fields[0].kind will hold Number.

          Spec2se converts from a structure representation to its S-
          expression equivalent.  Spec2fmt converts it to an array of
          Fmt structures mirroring it (equivalent to, but more effi-
          cient than, se2fmt(spec2se(spec)).t0)

        Data representation
          The above specifications do not define a format for the rep-
          resentation of the actual data. For convenience however,
          Format defines its own S-expression-based data format.  In
          this form, the fields in a record are represented by items
          in an S-expression list. A field containing sub-records is
          represented as a (possibly empty) list containing the sub-
          records; otherwise the value of a field may be an arbitrary
          S-expression.

          For example, a record corresponding to the structure speci-
          fication

               (name address (phone kind number))

          might look like:

               ("Jonny Dawes" "24 Crag Lane"
                    ((home "+44 7924 43535") (office "034 433 645")))

          Rec2val cracks such a record, rec, into its component val-
          ues, checking that it is structurally compatible with the
          specification, spec, and returning a tuple (fields, err).
          If it failed, fields will be nil, and err describes the
          error. Otherwise each member of fields, say v, holds the
          value of its equivalent field in spec. For fields without
          sub-records, v.val holds the field's value; otherwise v.recs
          holds an array with one member for each sub-record, each
          holding an array of fields defined recursively as above.

          Some file servers provide files to which a format specifica-
          tion may be written, and which provide a sequence of records
          in that format when read.  The Fmtfile type provides support
          for such files.  It provides the following operations:

          Fmtfile.new(spec)
               returns a new Fmtfile value that can be used to open
               files and read records conforming to the given spec.

          f.open(name)
               opens such a file, writes the format specification to
               it, and returns an Iobuf (see bufio(2)) ready for

     FORMAT(2)                                               FORMAT(2)

               reading the file.

          f.read
               reads a record from the file; its return is the same as
               that from rec2val.

     SOURCE
          /appl/lib/format.b

     SEE ALSO
          sexprs(2), bufio(2), sexprs(6)