uri.h File Reference

Finding files whose names encode coordinate values, via URI templates. More...

#include <stdbool.h>
#include <stdint.h>
#include <das3/defs.h>
#include <das3/time.h>
#include <das3/datum.h>

Include dependency graph for uri.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	DasUriField
	One sub-field within a named coordinate type. More...
struct	DasUriSegDef
	Definition of one coordinate type for use by the URI template parser. More...
struct	das_range
	A constraint on one coordinate (or sub-field) used to select matching files. More...

Macros
#define	DURI_MAX_PATH   2048
	Maximum length of a rendered URI / file path.

Enumerations
enum	DasUriProto
	Transport protocol, from the leading scheme of a URI template.

Functions
DAS_API DasErrCode	das_range_fromUtc (das_range *pRng, const char *sBeg, const char *sEnd)
	Initialize a das_range for the "time" coordinate from ISO-8601 UTC strings.
DAS_API DasErrCode	das_range_fromTime (das_range *pRng, const das_time *tBeg, const das_time *tEnd)
	Initialize a das_range for the "time" coordinate from das_time structs.
DAS_API DasErrCode	das_range_fromInt (das_range *pRng, const char *sCoord, int64_t nBeg, int64_t nEnd)
	Initialize a das_range for a named integer sub-field.
DAS_API DasErrCode	das_range_fromDatum (das_range *pRng, const char *sCoord, const das_datum *dmBeg, const das_datum *dmEnd)
	Initialize a das_range from pre-built das_datum values.
DAS_API const DasUriSegDef *	das_time_uridef (void)
	Return the built-in coordinate definition for the time coordinate.
DAS_API char **	das_uri_list (const char *sTemplate, const DasUriSegDef *pDef, int nRanges, const das_range *pRanges, size_t *pCount)
	Collect every path a template and ranges yield into one heap array.

Detailed Description

Finding files whose names encode coordinate values, via URI templates.

Archives commonly encode coordinate values (a date, an orbit number, a spacecraft clock count) in directory and file names. A URI template says where those values sit in a path so that, given a coordinate range, the matching files can be found by listing directories. Paths are never guessed: every directory that could hold a match is read.

Field tokens

$X short token, one character $(coord.field) qualified long token $(coord.field;mod=val) long token with modifiers shorthand, only for a coordinate with one field

Any DasUriField with a non-zero cShort gets a short token. A Voyager spacecraft clock registered with fields 'P' (partition), 'M' (mod64k) and 'S' (mod60) could be used as:

P$P/V1P$P_$x/C$M$S.DAT

The long form names the coordinate (DasUriSegDef.sCoord) and the field (DasUriField.sLong), the same dotted name that a das_range uses:

template: /data/$(time.year)/$(time.yday)/file_$(time.year)$(time.yday).dat range key: "time.year", "time.yday"

A token that names no registered coordinate or field is an error, never a silent wildcard. Short tokens take no modifiers, so the Autoplot form $(Y;pad=none) is not accepted.

Two variable-width fields may not sit side by side; put a literal between them or give one a fixed width.

Coordinate definitions

The engine knows nothing about time. Register any DasUriSegDef with DasUriTplt_register() before calling DasUriTplt_pattern(). The library ships one, das_time_uridef(), which supplies $Y $m $d $j $H $M $S. A coordinate such as an orbit counter is one more definition; no mapping from orbit to time is assumed.

Field values are non-negative integers written in decimal digits.

Wildcard and version tokens

$x Opaque wildcard. Of the files that match, the lexicographically last is used.

$v Version. Of the files that match, the greatest version is used, compared as the type= modifier says.

Neither is a coordinate. Files compete only when all their coordinate values agree, so a directory holding many days yields one file per day. In a directory name the token selects nothing: every matching directory is searched.

A path component may hold one $x or $v, and it must be followed by literal text or end the component.

Modifiers

pad=none The field is not zero padded and has variable width.

delta=N Accepted and preserved, but not yet used. A file is taken to cover one unit of the finest field in its path.

type=sep (default for $v) Split on '.' and compare each part as an integer, so 1.10.0 is later than 1.9.0.

type=int Compare as a single integer; for counters such as v01, v02.

type=alpha Compare as text, the same as $x.

Under type=sep and type=int two names can resolve to the same version, "v1" and "v01" for example. The lexicographically last is used and a warning is logged.

Protocols

A template with no scheme, or with file://, names local files, and the paths returned carry no scheme. http:// and https:// are parsed but can not be iterated yet: init_DasUriIter() fails for them.

Relationship to Autoplot URI templates

Autoplot's field codes are used wherever possible, so common templates read the same in both. The differences:

• Paths are always found by listing directories, never generated.
• Coordinates are not limited to time.
• $v compares numerically by default.

Function Documentation

das_range_fromUtc()

DAS_API DasErrCode das_range_fromUtc	(	das_range *	pRng,
		const char *	sBeg,
		const char *	sEnd
	)

Initialize a das_range for the "time" coordinate from ISO-8601 UTC strings.

Any format das_datum_fromStr() takes works here: "2025-10-01", "2025-288", "2025-10-15T06:00".

Parameters

pRng	Storage to initialise; all fields are overwritten.
sBeg	Range begin (inclusive).
sEnd	Range end (exclusive).

Returns

DAS_OKAY on success, a positive error code on parse failure.

das_range_fromTime()

DAS_API DasErrCode das_range_fromTime	(	das_range *	pRng,
		const das_time *	tBeg,
		const das_time *	tEnd
	)

Initialize a das_range for the "time" coordinate from das_time structs.

Parameters

pRng	Storage to initialise; all fields are overwritten.
tBeg	Inclusive range begin; copied.
tEnd	Exclusive range end; copied.

Returns

DAS_OKAY on success, a positive error code otherwise.

das_range_fromInt()

DAS_API DasErrCode das_range_fromInt	(	das_range *	pRng,
		const char *	sCoord,
		int64_t	nBeg,
		int64_t	nEnd
	)

Initialize a das_range for a named integer sub-field.

Parameters

pRng	Storage to initialise; all fields are overwritten.
sCoord	Sub-field name, e.g. "sclk.mod64k". Stored lower-cased; must fit in 31 chars.
nBeg	Inclusive range begin.
nEnd	Exclusive range end. nBeg > nEnd is a rollover, see das_range.

Returns

DAS_OKAY on success, a positive error code if sCoord is too long.

das_range_fromDatum()

DAS_API DasErrCode das_range_fromDatum	(	das_range *	pRng,
		const char *	sCoord,
		const das_datum *	dmBeg,
		const das_datum *	dmEnd
	)

Initialize a das_range from pre-built das_datum values.

The datums are copied, so they must own their bytes: a datum that refers to outside memory is refused. Use vtTime for "time" and numeric datums for sub-fields.

Parameters

pRng	Storage to initialise; all fields are overwritten.
sCoord	Coordinate or sub-field name. Stored lower-cased.
dmBeg	Inclusive begin datum.
dmEnd	Exclusive end datum.

Returns

DAS_OKAY on success, a positive error code if sCoord is too long or a datum does not own its bytes.

das_time_uridef()

DAS_API const DasUriSegDef * das_time_uridef

(

void

)

Return the built-in coordinate definition for the time coordinate.

short long name width range qualified token

---

$Y year 4 1678 - 2262 $(time.year) $m month 2 01 - 12 $(time.month) $d mday 2 01 - 31 $(time.mday) $j yday 3 001 - 366 $(time.yday) $H hour 2 00 - 23 $(time.hour) $M minute 2 00 - 59 $(time.minute) $S second 2 00 - 60 $(time.second)

The result is static: nothing to free, always valid.

das_uri_list()

DAS_API char ** das_uri_list	(	const char *	sTemplate,
		const DasUriSegDef *	pDef,
		int	nRanges,
		const das_range *	pRanges,
		size_t *	pCount
	)

Collect every path a template and ranges yield into one heap array.

For callers that want the whole list up front. Use the iterator to handle files as they are found.

das_range r;
das_range_fromUtc(&r, "2025-288", "2025-290");
 
size_t nCount = 0;
char** ppPaths = das_uri_list(
    "/data/$Y/$j/instrument_$Y$j_$v.cdf",
    das_time_uridef(),
    1, &r, &nCount
);
for(size_t i = 0; i < nCount; ++i)
    printf("%s\n", ppPaths[i]);
free(ppPaths);

Parameters

sTemplate	URI template string, as for DasUriTplt_pattern().
pDef	The one coordinate definition to register, or NULL for a template with only literals, $x and $v. Templates that need more than one must use the iterator.
nRanges	Number of entries in pRanges.
pRanges	Array of coordinate range constraints.
pCount	If not NULL, receives the number of paths.

Returns

A NULL-terminated array of paths, array and strings in one block released by a single free(). NULL on error or when nothing matches.