Skip to content

Commit 99e2307

Browse files
bruceravelbruceravel
committed
more on C readme
1 parent eebfaa3 commit 99e2307

File tree

2 files changed

+59
-32
lines changed

2 files changed

+59
-32
lines changed

‎c/README.md‎

Lines changed: 49 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import and interpret XDI-formatted data.
1212

1313
## API
1414

15-
### read an XDI file
15+
### Read an XDI file
1616

1717
Read an XDI file, store it's content in an XDIFile struct, and return
1818
an integer return code.
@@ -25,9 +25,9 @@ an integer return code.
2525
ret = XDI_readfile("mydata.xdi", xdifile);
2626
```
2727

28-
### interpret the XDI_readfile error code
28+
### Interpret the XDI_readfile error code
2929

30-
Interpret the return code by printing teh corresponding error massage
30+
Interpret the return code by printing the corresponding error message
3131
to the screen:
3232

3333
```C
@@ -51,23 +51,24 @@ or warning message from the most recent action. If an error code
5151
returns as non-zero, the content of `xdifile->error_message` will
5252
explain the meaning of the error code in English.
5353
54-
### test for required metadata
54+
### Test for required metadata
5555
5656
Test whether the **required** metadata was present in the XDI file.
5757
If `XDI_required_metadata` returns a non-zero value, the file is
5858
**not compliant** with the XDI specification.
5959
6060
```C
6161
j = XDI_required_metadata(xdifile);
62-
if (j != 0) {
63-
printf("\n# check for required metadata -- (requirement code %ld):\n%s\n", j, xdifile->error_message);
62+
if (j != 0 ) {
63+
printf("\n# check for required metadata -- (requirement code %ld):\n%s\n",
64+
j, xdifile->error_message);
6465
}
6566
```
6667

6768
Run `xdi_reader` agains `baddata/bad_30.xdi` for an example of a
6869
file which is non-compliant because of missing **required** metadata.
6970

70-
### test for recommended metadata
71+
### Test for recommended metadata
7172

7273
Test whether the **recommended** metadata was present in the XDI file.
7374
If `XDI_required_metadata` returns a non-zero value, the file is
@@ -76,8 +77,9 @@ highly useful to the interchange of the data contained in the file.
7677

7778
```C
7879
j = XDI_recommended_metadata(xdifile);
79-
if (j != ) {
80-
printf("\n# check for recommended metadata -- (recommendation code %ld):\n%s\n", j, xdifile->error_message);
80+
if (j != 0 ) {
81+
printf("\n# check for recommended metadata -- (recommendation code %ld):\n%s\n",
82+
j, xdifile->error_message);
8183
}
8284
```
8385
@@ -131,33 +133,58 @@ translation of a table of error messages into another language.
131133

132134
### XDI_readfile error codes
133135

134-
| code | message |
135-
| -1 | |
136-
| -2 | |
136+
| code | message |
137+
|------|--------------------------------------------------------------|
138+
| -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 |
142+
| -16 | number of columns changes in data table |
143+
| -32 | non-numeric value in data table: <word> |
144+
145+
Here `<word>` will be the the text that triggered the error.
137146

138147
### XDI_readfile warning codes
139148

140-
| 1 | |
141-
| 2 | |
149+
| code | message |
150+
|-------|--------------------------------------------------------------|
151+
| 1 | no mono.d_spacing given with angle array |
152+
| 2 | no line of minus signs '#-----' separating header from data |
153+
| 4 | contains unrecognized header lines |
154+
| 8 | element.symbol missing or not valid |
155+
| 16 | element.edge missing or not valid |
156+
| 32 | element.reference not valid |
157+
| 64 | element.ref\_edge not valid |
158+
| 128 | extension field used without versioning information |
159+
| 256 | Column.1 is not "energy" or "angle" |
160+
| 512 | invalid timestamp: format should be ISO 8601 (YYYY-MM-DD HH:MM:SS) |
161+
| 1024 | invalid timestamp: date out of valuid range |
162+
142163

143164
### XDI_required_metadata return codes
144165

145166
The return code from `XDI_required_metadata` can be interpreted
146167
bitwise. That is, a return code of 7 means that all three required
147168
metadata fields were missing.
148169

149-
| 1 | |
150-
| 2 | |
151-
| 4 | |
170+
| code | message |
171+
|------|-------------------------------------|
172+
| 1 | Element.symbol missing or not valid |
173+
| 2 | Element.edge missing or not valid |
174+
| 4 | Mono.d\_spacing missing |
175+
| 4 | Mono.d\_spacing not valid |
152176

153177
### XDI_recommended_metadata return codes
154178

155179
The return code from `XDI_recommended_metadata` can be interpreted
156180
bitwise. That is, a return code of 7 means that the first three
157181
recommendation metadata fields were missing.
158182

159-
| 1 | |
160-
| 2 | |
161-
| 4 | |
162-
| 8 | |
163-
| 16 | |
183+
| code | message |
184+
|------|-----------------------------------------------------|
185+
| 1 | Missing recommended metadata field: Facility.name |
186+
| 2 | Missing recommended metadata field: Facility.source |
187+
| 4 | Missing recommended metadata field: Beamline.name |
188+
| 8 | Missing recommended metadata field: Scan.start_time |
189+
| 16 | Missing recommended metadata field: Column.1 |
190+

‎c/xdifile.c‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ XDI_readfile(char *filename, XDIFile *xdifile) {
203203
firstline[strcspn(firstline, CRLF)] = '\0';
204204
nwords = make_words(firstline, cwords, 2);
205205
if (nwords < 1) {
206-
strcpy(xdifile->error_message, "not an XDI file, no versioning information in first line");
206+
strcpy(xdifile->error_message, "not an XDI file, no XDI versioning information in first line");
207207
for (j=0; j<=ilen; j++) {
208208
free(textlines[j]);
209209
}
@@ -213,7 +213,7 @@ XDI_readfile(char *filename, XDIFile *xdifile) {
213213
return ERR_NOTXDI;
214214
}
215215
if (strncasecmp(cwords[0], TOK_VERSION, strlen(TOK_VERSION)) != 0) {
216-
strcpy(xdifile->error_message, "not an XDI file, missing \"XDI/\" token in first line");
216+
strcpy(xdifile->error_message, "not an XDI file, no XDI versioning information in first line");
217217
for (j=0; j<=ilen; j++) {
218218
free(textlines[j]);
219219
}
@@ -653,10 +653,10 @@ XDI_required_metadata(XDIFile *xdifile) {
653653
}
654654

655655
strcpy(xdifile->error_message, "");
656-
if (ret & REQ_ELEM) { strcat(xdifile->error_message, "\tElement.symbol missing or not valid (1)\n"); }
657-
if (ret & REQ_EDGE) { strcat(xdifile->error_message, "\tElement.edge missing or not valid (2)\n"); }
658-
if (ret & REQ_NO_DSPACING) { strcat(xdifile->error_message, "\tMono.d_spacing missing (4)\n"); }
659-
if (ret & REQ_INVALID_DSPACING) { strcat(xdifile->error_message, "\tMono.d_spacing not valid (8)\n"); }
656+
if (ret & REQ_ELEM) { strcat(xdifile->error_message, "Element.symbol missing or not valid\n"); }
657+
if (ret & REQ_EDGE) { strcat(xdifile->error_message, "Element.edge missing or not valid\n"); }
658+
if (ret & REQ_NO_DSPACING) { strcat(xdifile->error_message, "Mono.d_spacing missing\n"); }
659+
if (ret & REQ_INVALID_DSPACING) { strcat(xdifile->error_message, "Mono.d_spacing not valid\n"); }
660660

661661
return ret;
662662
}
@@ -864,7 +864,7 @@ int XDI_validate_element(XDIFile *xdifile, char *name, char *value) {
864864
break;
865865
}
866866
}
867-
if (err>0) { strcpy(xdifile->error_message, "element.symbol not given or not valid"); }
867+
if (err>0) { strcpy(xdifile->error_message, "element.symbol missing or not valid"); }
868868

869869
} else if (strcasecmp(name, "edge") == 0) {
870870
err = WRN_NOEDGE;
@@ -874,7 +874,7 @@ int XDI_validate_element(XDIFile *xdifile, char *name, char *value) {
874874
break;
875875
}
876876
}
877-
if (err!=0) { strcpy(xdifile->error_message, "element.edge not given or not valid"); }
877+
if (err!=0) { strcpy(xdifile->error_message, "element.edge missing or not valid"); }
878878

879879
} else if (strcasecmp(name, "reference") == 0) {
880880
err = WRN_REFELEM;
@@ -884,7 +884,7 @@ int XDI_validate_element(XDIFile *xdifile, char *name, char *value) {
884884
break;
885885
}
886886
}
887-
if (err!=0) { strcpy(xdifile->error_message, "element.reference not given or not valid"); }
887+
if (err!=0) { strcpy(xdifile->error_message, "element.reference not valid"); }
888888

889889
} else if (strcasecmp(name, "ref_edge") == 0) {
890890
err = WRN_REFEDGE;
@@ -894,7 +894,7 @@ int XDI_validate_element(XDIFile *xdifile, char *name, char *value) {
894894
break;
895895
}
896896
}
897-
if (err!=0) { strcpy(xdifile->error_message, "element.ref_edge not given or not valid"); }
897+
if (err!=0) { strcpy(xdifile->error_message, "element.ref_edge not valid"); }
898898

899899
} else {
900900
err = 0;

0 commit comments

Comments
 (0)