Stream Routines for Parsing and Printing SOIFs

A SOIFStream contains one or more SOIF objects.

The general approach is that you use SOIF streams to create and process streams of many SOIF objects. Given a SOIF stream, you can parse it to get the SOIF objects from it. Use the parse() routine to get the next SOIF object in a SOIF stream. You can use SOIFStream_IsEOS() to check whether the last object has been parsed.

You can use filtering functions for a SOIF stream to specify that certain SOIF attributes are allowed or denied. If an attribute is allowed, you can parse and print that attribute for SOIF objects in the stream. If it is denied, you cannot parse or print that attribute of SOIF objects in the stream.

SOIF streams can be disk or memory based.

When you create a SOIFStream, you need to specify if you will be printing or parsing the SOIF stream, and if you will be using a memory- or disk-based stream. The functions you need to use will depend on what you will be doing with the SOIF stream.

For creating a SOIF streams into which you will be printing SOIFS, the functions are the following:

SOIF_PrintInitFile()

Creates a disk-based stream ready for printing.

SOIF_PrintInitStr()

Creates a memory-based stream ready for printing.

SOIF_PrintInitFn()

Creates a generic application-defined stream ready for printing. The given ”write_fn’ is used to print the stream.

To create SOIF stream from a file or a string containing SOIF, use the following functions:

SOIF_ParseInitFile()

Creates a disk-based stream ready for parsing. The stream is created from an input containing SOIF syntax.

SOIF_ParseInitStr()

Creates a memory-based stream ready for parsing. The stream is created from an input containing SOIF syntax.

SOIFStream objects have a caller-data field, which you can use as you like:

void *caller_data;   /* hook to be used by caller */

Use SOIFStream_Parse() to get the SOIF objects from the SOIF stream, and use SOIFStream_Print() to write SOIF objects to the SOIF stream.

When you’ve finished with the stream, close it by using SOIFStream_Finish(). Use SOIFStream_SetFinishFn() to trigger the given finish_fn function.

The following example code takes a SOIF stream in stdin and prints each SOIF in the stream to stdout. Notice that this code uses SOIF_ParseInitFile() to create the SOIFStream to parse the input file, and uses SOIF_PrintInitFile() to create the stream to print the SOIFs to stdout.

SOIFStream *soifin = SOIF_ParseInitFile(stdin);
SOIFStream *soifout = SOIF_PrintInitFile(stdout);
SOIF *s;
while (!SOIFStream_IsEOS(soifin)) {
    if ((s = SOIFStream_Parse(soifin)) {
        SOIFStream_print(soifout, s);
        SOIF_Free(s);
    }
}

SOIF_PrintInitFile

NSAPI_PUBLIC SOIFStream *SOIF_PrintInitFile(FILE *file)

Creates a disk-based stream ready for printing.

SOIF_PrintInitStr

NSAPI_PUBLIC SOIFStream *SOIF_PrintInitStr(SOIFBuffer *memory)

Creates a memory-based stream ready for printing.

SOIF_PrintInitFn

NSAPI_PUBLIC SOIFStream *SOIF_PrintInitFn(int (*write_fn)(void *data,char *buf, int bufsz), void *data)

Creates a generic application-defined stream ready for printing. The given write_fn is used to print the stream.

This function allows you to hook up your own routine for printing.

SOIF_ParseInitFile

NSAPI_PUBLIC SOIFStream *SOIF_ParseInitFile(FILE *fp)

Creates a disk-based stream ready for parsing. The file must contain SOIF-formatted data. The function reads SOIF data from the file object fp.

SOIF_ParseInitStr

NSAPI_PUBLIC SOIFStream *SOIF_ParseInitStr(char *buf, int bufsz)

Creates a memory-based stream ready for parsing. The character buffer must contain SOIF-formatted data.

SOIFStream_Finish

NSAPI_PUBLIC int SOIFStream_Finish(SOIFStream *)

Closes the stream when you have finished with it.

SOIFStream_SetFinishFn

NSAPI_PUBLIC int SOIFStream_SetFinishFn(SOIFStream *, int (*finish_fn)(SOIFStream *))

Allows you to hook up a function for cleaning up after the SOIF stream finishes its business. The finish_fn will be called when SOIFStream_Finish() has finished executing.

SOIFStream_Print

#define SOIFStream_Print(ss, s)

Prints another SOIF object to the SOIF stream ss. Returns 0 on success, or non-zero on error.

SOIFStream_Parse

#define SOIFStream_Parse(ss)

Parses and returns the next SOIF object in the SOIF stream.

SOIFStream_IsEOS

#define SOIFStream_IsEOS(s)

Returns 1 (true) if the SOIF stream has been exhausted.

SOIFStream_IsPrinting

#define SOIFStream_IsPrinting(s)

Returns 1 (true) if the SOIF has been set up in a stream by SOIF_PrintInitFile() or SOIF_PrintInitStr().

SOIFStream_IsParsing

#define SOIFStream_IsParsing(s)

Returns 1 (true) if the SOIF has been setup in a stream by SOIF_ParseInitFile() or SOIF_ParseInitStr().