Skip to content

Latest commit

 

History

History
387 lines (273 loc) · 10.6 KB

api.adoc

File metadata and controls

387 lines (273 loc) · 10.6 KB

DRAFT VEX parser and writer API description

1. Introduction

This document provides a terse description of the VEX parser and writer Application Program Interface (API). Whenever there is a non-backward compatible change in the API in a released version of the parser or writer, the first field in the version string will be incremented.

The remaining sections of this document list the API features, a history of non-backward compatible API changes, discouraged features, and lastly deprecated features.

2. API

2.1. VEX parser

The parser API includes functions and other programming language syntactic elements.

2.1.1. Functions

The functions in the parser API include all those that are externally visible in the source files:

  • vex_get.c

    This get_*() functions in this file make up the bulk of the C language parser interface. Examples of calls to these functions can be found in the vexf_get.c source file. The find_*() functions in this file are also part of the API, but their use is discouraged.

  • vexf_get.c

    The externally visible functions in this file make up the FORTRAN parser interface. The functions have explanations of their calling sequences in their source. The fget_*() functions are similar to the corresponding get_*() C language interface functions. Many of the fvex_*() functions, for example fvex_ra(), may also be useful in the C language.

Additionally for the C language, one function in the vex_util.c source file is part of the API:

  • vex_field()

    A synopsis of its calling sequence is included inline in the source.

2.1.2. C language syntactic elements

Beginning with v2.0.0 (released in FS 9.5.0, September 2001), the following C language syntactic elements became de facto parts of the API:

  • Symbolic names for the VEX parameter tokens (e.g., T_CHAN_DEF for chan_def) and the block names (e.g., B_FREQ for $FREQ).

  • Data structures for the VEX primitive statements. For some parameters that have only a single field, there is no explicit data structure, just a pointer to the data of that field. Direct use of these data structures/pointers is discouraged.

  • Memory linked lists that store the contents of a VEX file. Direct use of these lists is strongly discouraged.

The direct use of these discouraged syntactic elements can be avoided by using only the get_*() functions from vex_get.c along with vex_field() from vex_util.c. Instead, or in addition, the fget_*() functions from vexf_get.c can be used. The get_*() and fget_*() functions also enforce the context of the VEX data, e.g., which VEX parameters apply to which station and mode or globally.

Note
 Prior to v2.0.0, the last non-backward compatible changes in any of these syntactic elements was in v.1.2.0, released in FS 9.3.6, January, 1997. That update included the changes for VEX 1.5.

2.1.3. C language examples

Some examples of use of the parser in the C language are included in the examples subdirectory. There aren’t many of them at this time, but more may be added.

2.1.4. FORTRAN syntactic elements

Beginning with v2.0.0 (released in FS 9.5.0, September 2001), the character string representations of the symbolic names for the VEX parameter tokens (e.g., chan_def for T_CHAN_DEF) and block name tokens (e.g., FREQ for B_FREQ) became de facto parts of the API.

Note
 Prior to v2.0.0, the last non-backward compatible changes in any of these syntactic elements was in v.1.2.0, released in FS 9.3.6, January, 1997. That update included the changes for VEX 1.5.

2.2. VEX writer

The functions in the writer API include all functions in the source files:

  • vex_put.c — C language

    These are the create_*() functions.

  • vexf_put.c — FORTRAN

    These are the fcreate_*() functions.

3. Non-backward compatible API changes

3.1. v3

This sub-section covers the non-backward compatible feature changes in the v3 API, as compared to v2. That transition corresponds to the update to the VEX1-and-VEX2 capable parser from the VEX1-only capable parser. The latter having been distributed in FS version 10.0.0 and earlier releases, available at https://github.com/nvi-inc/fs (some subsequent FS releases may also contain the VEX1-only parser). All the changes were only to direct use of the VEX parameter data structures/pointers.

Note
 Being backward compatible does not imply being able to support VEX2. Please see the Deprecated features section below for details on the changes that are needed to support VEX2 usage of VEX parameters that existed in VEX1.

3.1.1. VEX parameter data structure changes

For all but two of the changes, a pointer to the VEX parameter data was replaced with a pointer to a data structure. The two that are different are source_type and VEX_rev.

The data structures for the following VEX parameters changed:

  • exper_name

    The storage was changed from a string value to the exper_name structure.

  • site_ID

    The storage was changed from a string value to the site_id structure.

  • source

    The storage was changed from a string value to the source structure.

  • source_type

    The storage was changed from a string value list to the source_type structure.

  • VEX_rev

    The storage was changed from a dvalue structure to a string value.

3.2. v2

This sub-section covers the non-backward compatible features in the v2 API, as compared to v1.2.2. The v2.0.0 version of the parser was released in FS 9.5.0, September 2001. All the changes were to functions.

3.2.1. Function changes

  • vex_get.c

    The calling sequence for the following functions changed:

    • get_scan_station()

    • get_scan_station_next()

  • vexf.c (now vexf_get.c)

    The calling sequence for the following function changed:

    • fget_scan_station()

4. Discouraged features

Discouraged features are acceptable for existing code, but should not be used in new code. Avoiding their use will insulate user code from most internal changes in the parser. Ideally all discouraged features should be eliminated from the API, but at this time that is not practical. Currently, all of the discouraged features are part of the C language parser API.

4.1. Functions

The following functions from vex_get.c are discouraged:

  • find_block()

  • find_def()

  • find_lowl()

  • find_next_def()

  • find_next_scan()

These are lower-level functions. It should be possible to restructure any use of them in terms of the get_*() functions in vex_get.c. However, if this appears to prevent some information from being accessed properly, please contact the maintainer.

4.2. Data structures

Direct use of the data structures for the VEX primitive statements is discouraged. Not using them will shield user code from changes in the data structures. The vex_field() function from vex_util.c should be used instead.

Direct use of the memory linked list of the VEX file data is strongly discouraged. Avoiding this will shield user code from changes in linked list structure. The get_*() functions in vex_get.c should be used instead.

5. Deprecated features

Deprecated features should be removed and replaced with updated features. Typically, this is needed because the functionality of the deprecated feature is too limited for use with VEX2. They will still work for VEX1 functionality. The deprecated features may be removed some day. Currently, the only deprecated features are functions.

Note
 The replacement functions are not plug replacements for the deprecated ones. The returned values and/or calling sequences have changed.

5.1. C language

5.1.1. vex_get.c

The following functions from vex_get.c are deprecated:

  • get_scan_source()

  • get_scan_source_next()

Use of those functions should be replaced with, respectively:

Important
 The returned values of the replacement functions are different.

  • get_scan_source2()

  • get_scan_source2_next()

5.1.2. vex_put.c

The following functions from vex_put.c are deprecated:

  • create_antenna_motion()

  • create_axis_type()

  • create_chan_def()

  • create_chan_def_states()

  • create_clock()

  • create_clock_early()

  • create_exper_name()

  • create_if_def()

  • create_pointing_sector()

  • create_site_ID()

  • create_source()

  • create_source_type()

  • create_vsn()

Use of those functions should be replaced with, respectively:

Important
 The calling sequences of the replacement functions are different.

  • create_antenna_motion2()

  • create_axis_type2()

  • create_chan_def2()

  • create_chan_def2_states()

  • create_clock_early2()

  • create_clock_early2()

  • create_exper_name2()

  • create_if_def2()

  • create_pointing_sector2()

  • create_site_ID2()

  • create_source2()

  • create_source_type2()

  • create_vsn2()

5.2. FORTRAN

5.2.1. vexf_get.c

The following function from vexf_get.c is deprecated:

  • fvex_scan_source()

Use of that function should be replaced with:

Important
 The calling sequence of the replacement function is different.
Caution
 There is a change from fvex_…​() to fget_…​(). The deprecated function was inconsistently named.

  • fget_scan_source2()

5.2.2. vexf_put.c

The following functions from vexf_put.c are deprecated:

  • fcreate_antenna_motion()

  • fcreate_axis_type()

  • fcreate_chan_def()

  • fcreate_chan_def_states()

  • fcreate_clock()

  • fcreate_clock_early()

  • fcreate_exper_name()

  • fcreate_if_def()

  • fcreate_pointing_sector()

  • fcreate_site_ID()

  • fcreate_source()

  • fcreate_source_type()

  • fcreate_vsn()

Use of those functions should be replaced with, respectively:

Important
 The calling sequences of the replacement functions are different.

  • fcreate_antenna_motion2()

  • fcreate_axis_type2()

  • fcreate_chan_def2()

  • fcreate_chan_def2_states()

  • fcreate_clock_early2()

  • fcreate_clock_early2()

  • fcreate_exper_name2()

  • fcreate_if_def2()

  • fcreate_pointing_sector2()

  • fcreate_site_ID2()

  • fcreate_source2()

  • fcreate_source_type2()

  • fcreate_vsn2()