format man page on Inferno

Man page or keyword search:  
man Server   579 pages
apropos Keyword Search (all sections)
Output format
Inferno logo
[printable version]

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 be a simple value,  or
       it can hold a list containing any number of sub-records, each holding a
       set of fields, recursively 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
       specification:

	      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  tex‐
       tual 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	struc‐
       ture.  If  a  member  is itself a list, it specifies a field containing
       sub-records: its first member gives the name of the field,  and	subse‐
       quent  members specify the fields in its sub-records.  For example, the
       above specification 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 specifica‐
       tion), 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  specification	 is  bad,  f  will  be	nil,  and  err
       describes  the error.  Otherwise, each member of f gives a field speci‐
       fied by se.  For example, given the above structure  definition,	 after
       executing:

		   se := Sexp.parse("(address (phone number))").t0;
		   (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 mirror‐
       ing    it    (equivalent	   to,	  but	  more	   efficient	 than,
       se2fmt(spec2se(spec)).t0)

   Data representation
       The  above specifications do not define a format for the representation
       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-expres‐
       sion.

       For example, a record corresponding to the structure specification

	      (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 values, 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 specification 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 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)

								     FORMAT(2)
[top]

List of man pages available for Inferno

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net