2.6. parse.pl - Simple Document Format Library
2.6.1. Purpose
This library provides support for handling SDF files.
2.6.2. Interface
require "parse.pl"; %SDF_IMAGE_EXTS = ... %sdf_driver = ... %sdf_report = ... %sdf_pagesize = ... $sdf_subtopic_cnt = ... $sdf_fmext = ... @sdf_include_path = ... @sdf_library_path = ... $sdf_lib = ... @sdf_if_start = ... @sdf_if_now = ... @sdf_if_yet = ... @sdf_if_else = ... $sdf_block_start = ... $sdf_block_type = ... @sdf_block_text = ... %sdf_block_param = ... @sdf_tbl_start = ... @sdf_tbl_state = ... @sdf_end = ... $sdf_cutting = ... $sdf_sections = ... @sdf_book_files = ... @sdf_report_names = ... &SdfLoadDrivers(@table); &SdfLoadPageSizes(@table); ($success, @records) = &SdfFetch($file); @records = &SdfParse(@sdf_strs); @result = &SdfConvert(*p_sdf, $target, *uses, %convert_var); &SdfInit(*var); ($text, $style, %attr) = &SdfNextPara(*sdf); ($text, %attr) = &SdfParseCell($cell); ($sect_type, $text, $style, %attr) = &SdfNextSection(*para, *state); $pts = &SdfPoints($measure); $pts = &SdfVarPoints($name); $info = &SdfPageInfo($page, $attr, $category); $sdf = &SdfJoin($style, $text, %attr); %attrs = &SdfAttrSplit($attrs); $attrtext = &SdfAttrJoin(*attr, $sep); $attrtext = &SdfAttrJoinSorted(*attr, $sep); &SdfAttrClean(*attr); &SdfAttrMap(*attr, $target, *map_to, *map_map, *map_attrs, $defaults); ($width, $height) = &SdfSizeGraphic($file); @result = &SdfColPositions($columns, $format, $margin); $prefix = &SdfHeadingPrefix($type, $level); $exit_code = &SdfSystem($cmd); $exit_code = &SdfQuietSystem($cmd); &SdfBatch($flags); &SdfHtmldoc($infile, $outfile); &SdfHtmldocHFOpts(); &SdfDelete($file); &SdfBookClean($ext); &SdfRenamePS($xx);
2.6.3. Description
The following symbols are occasionally accessed from other modules but aren't really for public consumption:
SDF_IMAGE_EXTS, sdf_if_start, sdf_if_now, sdf_if_yet, sdf_if_else, sdf_block_start, sdf_block_type, sdf_block_text, sdf_block_param, sdf_tbl_start, sdf_tbl_state, sdf_end, sdf_cutting, sdf_sections, sdf_book_files, sdf_report_names, SdfSystem, SdfBatch, SdfDelete, SdfBookClean, SdfRenamePS.
sdf_driver is a lookup table of valid format drivers. This table is build by SdfLoadDrivers.
sdf_report is a lookup table of valid reports. This table is build by SdfLoadReports.
sdf_pagesize is a lookup table of valid page sizes. This table is build by SdfLoadPageSizes.
sdf_subtopic_cnt is the counter of subtopics left during topics mode processing.
sdf_fmext is the extension of FrameMaker template files. Typically values are 'fm5' and 'fm4'.
sdf_include_path contains the list of directories searched for to find files specified in include macros. sdf_library_path contains the list of directories searched for to find libraries and modules. In both cases, the current directory and the document's directory are searched before these directories and sdf_lib is searched last of all.
SdfLoadDrivers loads a configuration table of drivers. The columns are:
- Name - the driver name
- Library - the library containing the subroutine
- Subroutine - the subroutine name.
Call this routine before calling SdfConvert.
SdfLoadPageSizes loads a configuration table of page sizes.
SdfFetch inputs an SDF file, ready for SdfConvert (i.e. ready conversion to another format). It returns 1 if the file is opened successfully.
SdfParse prepares an array of SDF strings for SdfConvert (i.e. for conversion to another format).
SdfConvert converts a list of sdf records to a list of target format paragraphs. The input records to this routine are usually read in by SdfFetch. The output records are typically output to a file, separated by newlines. %convert_var is the initial set of variables.
SdfInit initialises global data used during the conversion process.
SdfNextPara gets the next paragraph from an SDF buffer. Format drivers use this routine to process buffers. @sdf is the buffer which is updated ready for another call to this routine.
SdfParseCell parses an SDF cell into its components.
SdfNextSection gets the next section of a paragraph. Format drivers use this routine to process paragraphs. $para is the paragraph text which is updated ready for another call to this routine. $state is a state variable which this routines uses to help it keep state. sect_type is one of:
- string - a string normal paragraph text
- phrase - a phrase
- phrase_end - end of a phrase
- special - a special phrase (e.g. CHAR, IMPORT, etc.)
- an empty string - end of paragraph
For a string, text is the string, style and attr are empty. At the end of a phrase, text, style and attr are empty.
SdfPoints converts a measurement to points. This is required for calculations involving measurements.
SdfVarPoints converts an variable to points.
SdfPageInfo returns information about a page.
SdfJoin formats a style, text and attributes into a paragraph.
SdfAttrSplit parses a string of attributes into a set of name-value pairs.
SdfAttrJoin formats a set of name-value pairs (%attr) into a string. sep is the separator to use between attributes. The default separator is semi-colon.
SdfAttrJoinSorted formats a set of name-value pairs (%attr) into a string where the attributes are sorted by name. sep is the separator to use between attributes. The default separator is semi-colon.
SdfAttrClean removes target-specific attributes (for other targets) from a set of attributes. However, if the driver is 'raw', all attributes are kept.
SdfAttrMap maps a set of attributes using the configuration tables %map_to, %map_map and %map_attrs. $defaults is a string of default attributes. This routine is used by format drivers to merge user-supplied attributes with those in 'attribute' and 'style' configuration tables.
SdfSizeGraphic returns the width and height of a graphic stored in file. Zero is returned for both values if the size could not be extracted. File types currently supported are EPSI, PICT, GIF and PCX.
SdfColPositions returns a list of column positions given a total number of columns, a format attribute and a right margin.
SdfHeadingPrefix returns the prefix for the next heading. type is H, A or P and level is the heading level.
2.6.4. Limitations and future directions
Append/Prepend is not implemented for macros - is it needed for them?
SdfBookConvert currently generates (Unix) shell scripts. It should be generalised to support other operating systems?