.TH FORMAT 2.SH NAMEformat \- structured data interchange.SH SYNOPSIS.EXinclude "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);.EE.SH DESCRIPTION.B Formatprovides support for programs that wish to marshal and unmarshalstructured data. It is designed to enable a client torequest that the structure data is provided by the server in a particularformat, and for the server to be able to check that it is capable of providingthat format..PPA.I recordconsists of a set of.IR fields ,each represented by one element in an.IR sexprs (2)list. The content of a field can be a simple value, or it can hold a list containingany number of sub-records, each holding a set of fields, recursively defined as above..PPThe.B Fmtspectype defines the format for a field in a record..I Namegives the name of the field, and.I fieldsgives 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.B Fmtspecvalues can define the structure of all the fields in a record.Here is an example structure specification:.IP.EXName, 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),	}),};.EE.PPBy placing each field in the structure specificationat a known index, a link is made from the symbolic constants in the programto the textual field names..PPA structure specification may also be represented bya list of S-expressions, where each member of the listnames a field in the structure. If a member is itselfa list, it specifies a field containing sub-records: its first member gives the name of the field, andsubsequent members specify the fields in its sub-records.For example, the above specification could be written as theS-expression:.IP.EX(name address (phone number kind)).EE.PPThe.B Fmttype also defines a record structure, but.I "with respect"to an existing.B Fmtspecstructure specification.An.B Fmtvalue represents a field, and.I kindholds the index of that field in the original structure specification..PP.I Se2fmtconverts from an S-expression list,.IR se (a structure specification),to a set of.B Fmtvalues.The specification must be a subset of.IR spec ;i.e. each field in.I semust exist in.IR spec ..I Se2fmtreturns a tuple.BI ( "f, err" ) .If the specification is bad,.I fwill be nil, and.I errdescribes the error.Otherwise, each member of.I fgives a field specified by.IR se .For example, given the above structure definition, after executing:.IP.EX	se := Sexp.parse("(address (phone number))").t0;	(f, err) := se2fmt(spec, se);.EE.PP.IB f [0].kindwill hold the symbolic constant.BR Address ,and.IB f [1].fields[0].kindwill hold.BR Number ..PP.I Spec2seconverts from a structure representation to its S-expressionequivalent..I Spec2fmtconverts it to an array of.B Fmtstructures mirroring it (equivalent to, but more efficient than,.BI se2fmt(spec2se( spec )).t0\fR).SS "Data representation"The above specifications do not define a format for therepresentation of the actual data. For convenience however,.B Formatdefines its own S-expression-based data format.In this form, the fields in a record are represented by itemsin an S-expression list. A field containing sub-records is represented asa (possibly empty) list containing the sub-records;otherwise the value of a field may be an arbitrary S-expression..PPFor example, a record corresponding to thestructure specification.IP.EX(name address (phone kind number)).EE.PPmight look like:.IP.EX("Jonny Dawes" "24 Crag Lane"	((home "+44 7924 43535") (office "034 433 645"))).EE.PP.I Rec2valcracks such a record,.IR rec ,into its component values, checkingthat it is structurally compatible with the specification,.IR spec ,and returning a tuple.BI ( "fields, err" ) .If it failed,.I fieldswill be nil, and.I errdescribes the error. Otherwiseeach member of.IR fields ,say.IR v ,holds the value of its equivalent field in.IR spec .For fields without sub-records,.IB v .valholds the field's value;otherwise.IB v .recsholds an array with one member for eachsub-record, each holding an array of fieldsdefined recursively as above..PPSome file serversprovide files to which a format specification maybe written, and which provide a sequence of recordsin that format when read.The.B Fmtfiletype provides support for such files.It provides the following operations:.TP.BI Fmtfile.new( spec )returns a new.B Fmtfilevaluethat can be used to open files and read recordsconforming to the given.IR spec ..TP.IB f .open(\fIname\fP)opens such a file, writes the format specification to it,and returns an.B Iobuf(see.IR bufio (2))ready for reading the file..TP.IB f .readreads a record from the file; its return is thesame as that from.BR rec2val ..SH SOURCE/appl/lib/format.b.SH SEE ALSO.IR sexprs (2),.IR bufio (2),.IR sexprs (6)