Page 1 of 1
Posted: Tue Jan 10, 2012 2:06 pm
This topic is for documenting API requirements gleaned from discussions elsewhere in the forum. Discussion of these requirements generally belongs in other topics. Editorial comments about the requirements documented here are welcome in this topic, but be aware that I plan to delete such comments after addressing them.
That particular requirements are listed in this topic is not meant to imply group agreement on them. Some are gleaned from only one or two posts, and most are generalized and/or reworded. All listed requirements are hyperlinked to sources elsewhere in this forum, though some link targets are more general than others, and in some cases one of several possible link targets had to be selected. Please expect that the requirements documented here will be updated and perhaps deleted as discussion proceeds elsewhere in the forum.
Re: Requirements List
Posted: Tue Jan 10, 2012 3:52 pm
- The API will support both CIF 1.1 and CIF 2.0. (Degree and form of support for non-standard features and other syntax variants is yet to be determined.)
- The API will support both (1) fast, small-footprint operation, and (2) a rich, expressive, and convenient public interface; these may be provided by separate branches of the API.
- The API will support inputting and parsing CIF text from external sources.
- The API will support outputting logical CIF structure and content to external sinks as well-formed CIF text.
- Between source, if any, and sink, if any, and in memory where applicable, the API will support all CIF-compatible inquiries and modifications of logical CIF structure and data, including, but not necessarily limited to
- adding and removing data blocks
- adding save frames to and removing them from data blocks
- determining the presence of a data names and their contexts (whether looped; other names in the same loop) within a block or frame
- adding data names to a chosen context (for example, to a particular loop) within a block or frame
- removing data names and their associated data values from a block or frame
- querying the data value(s) associated with a specified data name within a block or frame
- replacing one or more data values associated with a specified data name within a block or frame
- querying the set(s) of related data values for a chosen context within a block or frame (for example, retrieving all the values belonging to a chosen packet of a chosen loop)
- replacing one or more of the data values belonging to one or more of the sets of related data values for a chosen context within a block or frame (for example, replacing selected values in a chosen packet of a chosen loop)
- adding one or more sets of related data values to a chosen context within a block or frame (for example, adding a packet to a chosen loop)
- removing one or more sets of related data values for a chosen context within a block or frame (for example, removing a selected packet from a chosen loop)
- The API will support optional validation. (More detailed requirements to be determined.) That validation is optional implies that to the greatest extent feasible, all the API's features will be available when validation is disabled.
- The core API will be targeted at C99, and it will avoid any incompatibility with C89. (This is more restrictive than targeting C89 or C99 alone would be.)
- The API will be accessible from other languages, including, at minimum, C++, Fortran 77, Fortran 95, Python, and Java.
- The API will everywhere support multiple CIF files simultaneously open for reading and / or writing (including updating), and where applicable, it will support multiple independent logical CIFs in-memory simultaneously.
- The API will provide for error recovery and informative error reporting, especially for parsing and validation operations.