Functions | |
| int | cif_parse (FILE *stream, struct cif_parse_opts_s *options, cif_tp **cif) |
| Parses a CIF from the specified stream using the library's built-in parser. | |
| int | cif_parse_options_create (struct cif_parse_opts_s **opts) |
| Allocates a parse options structure and initializes it with default values. | |
| int | cif_parse_error_ignore (int code, size_t line, size_t column, const UChar *text, size_t length, void *data) |
| A CIF parse error handler function that ignores all errors. | |
| int | cif_parse_error_die (int code, size_t line, size_t column, const UChar *text, size_t length, void *data) |
A CIF parse error handler function that interrupts the parse on any error, returning code. | |
| int | cif_write (FILE *stream, struct cif_write_opts_s *options, cif_tp *cif) |
Formats the CIF data represented by the cif handle to the specified output stream. | |
| int | cif_write_options_create (struct cif_write_opts_s **opts) |
| Allocates a write options structure and initializes it with default values. | |
| int cif_parse | ( | FILE * | stream, | |
| struct cif_parse_opts_s * | options, | |||
| cif_tp ** | cif | |||
| ) |
Parses a CIF from the specified stream using the library's built-in parser.
The data are interpreted as a standalone CIF providing zero or more data blocks to add to the provided or a new managed CIF object. The caller asserts that the new and any pre-existing data are part of the same logical CIF data set, therefore it constitutes a parse error for any data blocks in the provided CIF to have block codes that match that of one of the existing blocks.
If a new CIF object is created via this function then the caller assumes responsibility for releasing its resources at an appropriate time via cif_destroy().
CIF handler callbacks. The parse options allow the caller to register a variety of callback functions by which the parse can be tracked and influenced. Most of these are wrapped together in the handler option, by which a cif_handler_tp object can be provided. Handler functions belonging to such a handler will be called when appropriate during CIF parsing, and the returned navigational signals direct which parts of the input data are included in the in-memory CIF rpresentation, if any, constructed by the parse. To some extent, the CIF can be modified during parse time, too; for example, loop categories may be assigned via callback.
Error handler callback. The parse options also afford the caller an opportunity to specify an error-handler callback. The provided function will be invoked whenever any error is detected in the CIF input, and any return code other than CIF_OK will be immediately returned to the cif_parse() caller, aborting the remainder of the parse. This feature can be used to record or display information about the errors encountered, and / or to selectively ignore some errors (invoking the built-in recovery approach). Two pre-built error callbacks are provided: cif_parse_error_ignore() and cif_parse_error_die(). If no error handler is specified by the caller then cif_parse_error_die() is used.
Syntax-only mode. If the cif argument is NULL then the parse is performed in syntax-only mode. Errors in CIF syntax will be detected as normal, but some semantic errors, such as duplicate data names, frame codes, or block codes will not be detected. Also, the handles provided to CIF handler functions during the parse may be NULL or may yield less information in this mode.
| [in,out] | stream | a FILE * from which to read the raw CIF data; must be a non-NULL pointer to a readable stream, which will typically be read to its end. This stream should be open in BINARY mode (e.g. fopen() mode "rb") on any system where that makes a difference. The caller retains ownership of this stream. |
| [in] | options | a pointer to a struct cif_parse_opts_s object describing options to use while parsing, or NULL to use default values for all options |
| [in,out] | cif | controls the disposition of the parsed data. If NULL, then the parsed data are discarded. Otherwise, they are added to the CIF to which this pointer refers. If a NULL handle is initially recorded at the referenced location then a new CIF is created to receive the data and its handle is recorded here. In the latter case, ownership of the new CIF goes to the caller. |
CIF_OK on a successful parse, even if the results are discarded, or an error code (typically CIF_ERROR ) on failure. In the event of a failure, a new CIF object may still be created and returned via the cif argument, or the provided CIF object may still be modified. | int cif_parse_options_create | ( | struct cif_parse_opts_s ** | opts | ) |
Allocates a parse options structure and initializes it with default values.
Obtaining a parse options structure via this function insulates programs against additions to the option list in future versions of the library. Programs may create cif_parse_opts_s objects by other means -- for example, by allocating them on the stack -- but the behavior of programs that do may be undefined if they are dynamically linked against a future version of the library that adds fields to the structure definition, perhaps even if they are re-compiled against revised library headers. This is not an issue for statically-linked programs that fully initialize their options.
On successful return, the provided options object belongs to the caller. An options structure as provided by this function may safely be freed, or its members overwritten, without concern for freeing memory referenced by the members. The user is responsible for accommodating any deviation from those characteristics that are introduced to the structure after this function provides it.
| [in,out] | opts | a the location where a pointer to the new parse options structure should be recorded. The initial value of *opts is ignored, and is overwritten on success. |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure. | int cif_write | ( | FILE * | stream, | |
| struct cif_write_opts_s * | options, | |||
| cif_tp * | cif | |||
| ) |
Formats the CIF data represented by the cif handle to the specified output stream.
By default, the output is in CIF 2.0 format, but the write options can be used to request CIF 1.1 format instead. These extra considerations apply to CIF 1.1 output mode:
cif_parse()). As a result, however, parsers that do not recognize the line folding protocol may interpret some of the resulting values differently than was intended.Ownership of the arguments does not transfer to the function.
| [in,out] | stream | a FILE * to which to write the CIF format output; must be a non-NULL pointer to a writable stream. In the event that the write options request CIF 1.1 output, this file should be open in text mode (on those systems that have distinct text and binary modes) |
| [in] | options | a pointer to a struct cif_write_opts_s object describing options to use for writing, or NULL to use default values for all options |
| [in] | cif | a handle on the CIF object to serialize to the specified stream |
CIF_OK if the data are fully written, or else an error code (typically CIF_ERROR, or CIF_DISALLOWED_CHAR or CIF_DISALLOWED_VALUE in CIF 1.1 mode). The stream state is undefined after a failure. | int cif_write_options_create | ( | struct cif_write_opts_s ** | opts | ) |
Allocates a write options structure and initializes it with default values.
Obtaining a write options structure via this function insulates programs against additions to the option list in future versions of the library. Programs may create cif_write_opts_s objects by other means -- for example, by allocating them on the stack -- but the behavior of programs that do is undefined if they are dynamically linked against a future version of this API that adds fields to the structure definition. Statically-linked programs that fully initialize their write options structures are not subject to such issues.
On successful return, the provided options object belongs to the caller. An options structure as provided by this function may safely be freed, or its members overwritten, without concern for freeing memory referenced by the members. The user is responsible for accommodating any deviation from those characteristics that are introduced to the structure after this function provides it.
| [in,out] | opts | a the location where a pointer to the new write options structure should be recorded. The initial value of *opts is ignored, and is overwritten on success. |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure. Copyright 2014, 2015 John C. Bollinger