Skip to content

Commit 37f9383

Browse files
bruceravelbruceravel
committed
yet more work on the c readme
1 parent 8e577c2 commit 37f9383

File tree

3 files changed

+77
-25
lines changed

3 files changed

+77
-25
lines changed

‎c/README.md‎

Lines changed: 63 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,50 @@
33
This is a C implementation of the XDI specification. While the XDI
44
specification is not difficult to implement correctly, we encourage
55
people implementing XDI readers in other languages to base their
6-
implementation on `libxdifile`. That way, the behaviour of XDI
6+
implementation on `libxdifile`. That way, the behavior of XDI
77
readers in different languages is guaranteed to be identical (or at
88
least very similar).
99

1010
See `xdi_reader.c` for an example of a C program using `libxdifile` to
1111
import and interpret XDI-formatted data.
1212

13+
`libxdifile` was written by Matt Newville and Bruce Ravel.
14+
15+
## XDIFile struct
16+
17+
This is the content of the XDIFile struct. It will contain the entire
18+
contents of the XDI file along with a few particularly important items
19+
(d-spaing, element, and edge).
20+
21+
| attribute | type | explanation |
22+
| --------------- | ------------------ | ----------- |
23+
| nmetadata | long | number of metadata fields |
24+
| narrays | long | number of arrays in data table |
25+
| npts | long | number of rows in data table |
26+
| narray\_labels | long | number of array labels |
27+
| error\_lineno | long | the line number of a line returning an error |
28+
| dspacing | double | the Mono.d-spacing value |
29+
| xdi\_libversion | char* | the `libxdifile` version number |
30+
| xdi\_version | char* | the XDI file specification version number from the file |
31+
| extra\_version | char* | versioning information for extension fields |
32+
| filename | char* | the name of the XDI file |
33+
| element | char* | the 1, 2, or 3 letter symbol of the element |
34+
| edge | char* | the 1 or 2 letter symbol of the edge |
35+
| comments | char* | the user supplied comments from the XDI file |
36+
| error\_line | char* | the line returning an error |
37+
| error\_message | char* | the error message |
38+
| array\_labels | array of char* | array of labels for arrays in the data table |
39+
| array\_units | array of char* | array of units for arrays in the data table |
40+
| meta\_families | array of char* | array of family names found among the metadata, indexed to nmetadata |
41+
| meta\_keywords | array of char* | array of keyword names found among the metadata, indexed to nmetadata |
42+
| meta\_values | array of char* | array of values found among the metadata, indexed to nmetadata |
43+
| array | of array of double | the data table |
44+
| nouter | long | |
45+
| outer\_label | array char* | |
46+
| outer\_array | array of double | |
47+
| outer\_breakpts | array of long | |
48+
49+
1350
## API
1451

1552
### Read an XDI file
@@ -65,7 +102,7 @@ If `XDI_required_metadata` returns a non-zero value, the file is
65102
}
66103
```
67104

68-
Run `xdi_reader` agains `baddata/bad_30.xdi` for an example of a
105+
Run `xdi_reader` against `baddata/bad_30.xdi` for an example of a
69106
file which is non-compliant because of missing **required** metadata.
70107

71108
### Test for recommended metadata
@@ -83,7 +120,7 @@ highly useful to the interchange of the data contained in the file.
83120
}
84121
```
85122
86-
Run `xdi_reader` agains `baddata/bad_32.xdi` for an example of a
123+
Run `xdi_reader` against `baddata/bad_32.xdi` for an example of a
87124
file which is missing **recommended** metadata.
88125
89126
@@ -125,6 +162,20 @@ table. The return value is -1 if the array cannot be retrieved.
125162

126163
The array names are held in the `Column.N` metadata fields.
127164

165+
### Destroy and deallocate the XDIFile struct
166+
167+
To deallocate the memory from the XDIFile struct, do this:
168+
169+
```C
170+
XDI_cleanup(xdifile, ret);
171+
```
172+
173+
Here, the second argument is the return code from the call to
174+
XDI_readfile. That is needed so that the cleanup method knows how
175+
much stuff needs to be freed.
176+
177+
178+
128179
## Error codes
129180
130181
Here is a list of all error codes and their English explanation. An
@@ -134,20 +185,20 @@ translation of a table of error messages into another language.
134185
### XDI_readfile error codes
135186
136187
| code | message |
137-
| ---- | ------------------------------------------------------------ |
188+
| ---: | ------------------------------------------------------------ |
138189
| -1 | not an XDI file, no XDI versioning information in first line |
139-
| -2 | `<word>` -- invalid family name in metadata |
140-
| -4 | `<word>` -- invalid keyword name in metadata |
141-
| -8 | `<word>` -- not formatted as Family.Key: Value |
190+
| -2 | `<word>` -- invalid family name in metadata |
191+
| -4 | `<word>` -- invalid keyword name in metadata |
192+
| -8 | `<word>` -- not formatted as Family.Key: Value |
142193
| -16 | number of columns changes in data table |
143-
| -32 | non-numeric value in data table: `<word>` |
194+
| -32 | non-numeric value in data table: `<word>` |
144195
145196
Here `<word>` will be the the text that triggered the error.
146197
147198
### XDI_readfile warning codes
148199
149200
| code | message |
150-
| ----- | ------------------------------------------------------------ |
201+
| ----: | ------------------------------------------------------------ |
151202
| 1 | no mono.d_spacing given with angle array |
152203
| 2 | no line of minus signs '#-----' separating header from data |
153204
| 4 | contains unrecognized header lines |
@@ -158,7 +209,7 @@ Here `<word>` will be the the text that triggered the error.
158209
| 128 | extension field used without versioning information |
159210
| 256 | Column.1 is not "energy" or "angle" |
160211
| 512 | invalid timestamp: format should be ISO 8601 (YYYY-MM-DD HH:MM:SS) |
161-
| 1024 | invalid timestamp: date out of valuid range |
212+
| 1024 | invalid timestamp: date out of valid range |
162213
163214
164215
### XDI_required_metadata return codes
@@ -168,7 +219,7 @@ bitwise. That is, a return code of 7 means that all three required
168219
metadata fields were missing.
169220
170221
| code | message |
171-
| ---- | ----------------------------------- |
222+
| ---: | ----------------------------------- |
172223
| 1 | Element.symbol missing or not valid |
173224
| 2 | Element.edge missing or not valid |
174225
| 4 | Mono.d\_spacing missing |
@@ -181,7 +232,7 @@ bitwise. That is, a return code of 7 means that the first three
181232
recommendation metadata fields were missing.
182233
183234
| code | message |
184-
| ---- | --------------------------------------------------- |
235+
| ---: | --------------------------------------------------- |
185236
| 1 | Missing recommended metadata field: Facility.name |
186237
| 2 | Missing recommended metadata field: Facility.source |
187238
| 4 | Missing recommended metadata field: Beamline.name |

‎c/xdifile.c‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -611,7 +611,7 @@ XDI_defined_family(XDIFile *xdifile, char *family) {
611611
(strcasecmp(family, "sample") == 0) ||
612612
(strcasecmp(family, "scan") == 0) ||
613613
(strcasecmp(family, "element") == 0) ||
614-
(strcasecmp(family, "column") == 0)) {
614+
(strcasecmp(family, "column") == 0)) {
615615
return 1;
616616
} else {
617617
return 0;
@@ -662,11 +662,11 @@ XDI_required_metadata(XDIFile *xdifile) {
662662
}
663663

664664

665-
/* Facility.name: 1 */
666-
/* Facility.source: 2 */
667-
/* Beamline.name: 4 */
668-
/* Scan.start_time: 8 */
669-
/* Column.1=(energy|angle): 16, 32 */
665+
/* Facility.name: 1 */
666+
/* Facility.source: 2 */
667+
/* Beamline.name: 4 */
668+
/* Scan.start_time: 8 */
669+
/* Column.1: (energy|angle): 16 */
670670

671671
_EXPORT(int)
672672
XDI_recommended_metadata(XDIFile *xdifile) {
@@ -706,7 +706,6 @@ XDI_recommended_metadata(XDIFile *xdifile) {
706706
if (ret & 16) { strcat(xdifile->error_message, "Missing recommended metadata field: Column.1\n"); }
707707

708708
return ret;
709-
710709
}
711710

712711

@@ -830,6 +829,7 @@ int XDI_validate_scan(XDIFile *xdifile, char *name, char *value) {
830829

831830
/* printf("======== %s %s\n", name, value); */
832831

832+
err = 0;
833833
strcpy(xdifile->error_message, "");
834834

835835
if (strcasecmp(name, "start_time") == 0) {
@@ -854,6 +854,7 @@ int XDI_validate_element(XDIFile *xdifile, char *name, char *value) {
854854
int n_edges = sizeof(ValidEdges)/sizeof(char*);
855855
int n_elems = sizeof(ValidElems)/sizeof(char*);
856856

857+
err = 0;
857858
strcpy(xdifile->error_message, "");
858859

859860
if (strcasecmp(name, "symbol") == 0) {

‎c/xdifile.h‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,12 +58,12 @@ typedef struct {
5858

5959
} XDIFile;
6060

61-
_EXPORT(int) XDI_readfile(char *filename, XDIFile *xdifile) ;
62-
_EXPORT(int) XDI_get_array_index(XDIFile *xdifile, long n, double *out);
63-
_EXPORT(int) XDI_get_array_name(XDIFile *xdifile, char *name, double *out);
64-
_EXPORT(int) XDI_required_metadata(XDIFile *xdifile);
65-
_EXPORT(int) XDI_defined_family(XDIFile *xdifile, char *family);
66-
_EXPORT(int) XDI_validate_item(XDIFile *xdifile, char *family, char *name, char *value);
61+
_EXPORT(int) XDI_readfile(char *filename, XDIFile *xdifile) ;
62+
_EXPORT(int) XDI_get_array_index(XDIFile *xdifile, long n, double *out);
63+
_EXPORT(int) XDI_get_array_name(XDIFile *xdifile, char *name, double *out);
64+
_EXPORT(int) XDI_required_metadata(XDIFile *xdifile);
65+
_EXPORT(int) XDI_defined_family(XDIFile *xdifile, char *family);
66+
_EXPORT(int) XDI_validate_item(XDIFile *xdifile, char *family, char *name, char *value);
6767
_EXPORT(void) XDI_cleanup(XDIFile *xdifile, long err);
6868

6969
/* Tokens used in XDI File */

0 commit comments

Comments
 (0)