hare::module
hare::module provides an interface to the module system used by this Hare implementation, as well as to the Hare cache. Note that these interfaces may not be portable to other Hare implementations.
Note that much of this module's design is an implementation detail of the Hare toolchain, and is not subject to any future compatibility guarantees.
Index
Types
type context = struct {
harepath: str,
harecache: str,
tags: []str,
};
type location = (*path::buffer | ast::ident);
type module = struct {
name: str,
ns: ast::ident,
path: str,
srcs: srcset,
deps: [](size, ast::ident),
};
type srcset = struct {
mtime: time::instant,
dirs: []str,
seentags: []str,
ha: []str,
s: []str,
o: []str,
sc: []str,
};
type tag = struct {
name: str,
include: bool,
};
Errors
type dep_cycle = ![]str;
type errcontext = !(str, *error);
type error = !(fs::error | io::error | path::error | parse::error | utf8::invalid | file_conflict | not_found | dep_cycle | tag_has_dot | tag_bad_format | errcontext);
type file_conflict = ![]str;
type not_found = !void;
type tag_bad_format = !void;
type tag_has_dot = !void;
Functions
fn find(ctx: *context, loc: location) ((str, srcset) | error);
fn finish(mod: *module) void;
fn finish_error(e: error) void;
fn finish_srcset(srcs: *srcset) void;
fn format(out: io::handle, mod: *module) (size | io::error);
fn format_srcset(out: io::handle, srcs: *srcset) (size | io::error);
fn format_tags(out: io::handle, tags: ([]str | []tag)) (size | io::error);
fn free_slice(mods: []module) void;
fn gather(ctx: *context, out: *[]module, mod: location) (size | error);
fn get_cache(harecache: str, modpath: str) (str | error);
fn locstr(loc: location) str;
fn next(it: *fs::iterator) (fs::dirent | done | fs::error);
fn outdated(target: str, deps: []str, mtime: time::instant) bool;
fn parse_deps(files: str...) ([]ast::ident | error);
fn parse_tags(s: str) ([]tag | error);
fn strerror(e: error) str;
fn tags_compat(have: []str, want: []tag) bool;
Types
type context
type context = struct {
harepath: str,
harecache: str,
tags: []str,
};
A container struct for context, used by gather.
type location
type location = (*path::buffer | ast::ident);
The location of a module
type module
type module = struct {
name: str,
ns: ast::ident,
path: str,
srcs: srcset,
deps: [](size, ast::ident),
};
A hare module.
type srcset
type srcset = struct {
mtime: time::instant,
dirs: []str,
seentags: []str,
ha: []str,
s: []str,
o: []str,
sc: []str,
};
A set of sources for a module, filtered by a set of tags.
type tag
type tag = struct {
name: str,
include: bool,
};
A file tag, e.g. +x86_64, or -libc.
Errors
type dep_cycle
type dep_cycle = ![]str;
A dependency cycle error.
type errcontext
type errcontext = !(str, *error);
Context for another error.
type error
type error = !(fs::error | io::error | path::error | parse::error | utf8::invalid | file_conflict | not_found | dep_cycle | tag_has_dot | tag_bad_format | errcontext);
Tagged union of all possible error types. Must be freed with finish_error unless it's passed to strerror.
type file_conflict
type file_conflict = ![]str;
Two files in a module have the same basename and extension, and the same number of compatible tags with the input tagset, so it is unknown which should be used.
type not_found
type not_found = !void;
A module was not found.
type tag_bad_format = !void;
Generic badly formatted tag error.
type tag_has_dot
type tag_has_dot = !void;
A tag contains a dot.
Functions
fn find
fn find(ctx: *context, loc: location) ((str, srcset) | error);
Find the on-disk path and set of source files for a given module. The path is statically allocated and may be overwritten on subsequent calls.
fn finish
fn finish(mod: *module) void;
Free the resources associated with a module.
fn finish_error
fn finish_error(e: error) void;
Free the resources associated with an error.
fn finish_srcset
fn finish_srcset(srcs: *srcset) void;
Frees the resources associated with a srcset.
fn format(out: io::handle, mod: *module) (size | io::error);
Formats a module to an io::handle.
fn format_srcset(out: io::handle, srcs: *srcset) (size | io::error);
Formats a srcset to an io::handle.
fn format_tags(out: io::handle, tags: ([]str | []tag)) (size | io::error);
Formats a set of tags to an io::handle in "+tag1-tag2" format.
fn free_slice
fn free_slice(mods: []module) void;
Free all the modules in a slice of modules, and then the slice itself.
fn gather
fn gather(ctx: *context, out: *[]module, mod: location) (size | error);
Gather a module and all its dependencies, appending them to an existing slice, deduplicated, in reverse topological order, returning the index of the input module within the slice. Dependencies will also be written to the cache.
fn get_cache
fn get_cache(harecache: str, modpath: str) (str | error);
Gets the cache directory for a given module, given the value of 'harecache'. The result is statically allocated and will be overwritten on subsequent calls. An error is returned if the resulting path would be longer than path::MAX.
fn locstr
fn locstr(loc: location) str;
Returns a string representation of a location. The result must be freed by the caller.
fn next
fn next(it: *fs::iterator) (fs::dirent | done | fs::error);
Wrapper for fs::next that only returns valid submodule directories.
fn outdated
fn outdated(target: str, deps: []str, mtime: time::instant) bool;
Checks if the file at 'target' is out-of-date, given a list of dependency files, and the last time the deps list changed. If "target" doesn't exist, returns true. If any of the deps don't exist, they are skipped.
fn parse_deps
fn parse_deps(files: str...) ([]ast::ident | error);
Get the list of dependencies referred to by a set of source files. The list will be sorted alphabetically and deduplicated.
fn parse_tags(s: str) ([]tag | error);
Parses tags from a string. The tag themselves are borrowed from the input, but the caller must free the slice returned.
fn strerror
fn strerror(e: error) str;
Turns an error into a human-readable string. The result is statically allocated. Consumes the error.
fn tags_compat(have: []str, want: []tag) bool;
Checks if a set of tags are compatible with a tag requirement.