The type for file formats: the constants that differ between the two.

The type for the identity of the executable that wrote a file. exe is its exe_identity, and digest is the lowercase hexadecimal MD5 of its contents when it wrote. An executable at exe whose file_digest differs is not the one that wrote the file.

file_digest path is the lowercase hexadecimal MD5 of the contents of the file at path, or None when the file cannot be read.

absolute path is path when it is absolute, and path below the current directory otherwise. It does not normalize.

executable is Sys.executable_name made absolute against the directory the process started in, so a later change of directory leaves it right. It is Sys.executable_name unchanged when that directory could not be read.

build_dir ~path is the build directory that path lies in, normalized and separated by '/', or None when no component of path starts with _build. It is "/w/_build" for "/w/_build/default/test/t.exe", and "/w/_build_ci" for "/w/_build_ci/.sandbox/3f/default". The first matching component decides whatever it names, so every path below /home/u/_build_farm has that directory as its build directory.

build_root ~path is the parent directory of build_dir ~path, or None when there is none.

exe_identity ~exe is the normalized path of exe below its build directory, without the sandbox prefix, or its normalized absolute path when exe lies below no build directory. It is the exe of an identity, and it is never "". Only the directories above exe can be its build directory, so an executable whose own name starts with _build lies below none. The build context is part of the result, as in default/test/t.exe, and the build directory is not.

data_dir f ~build_dir is <build_dir>/_<f.dir>.

standalone_data_dir f ~root is <root>/_windtrap/<f.dir>, where an executable below no build directory writes the files of f.

output_file f ~exe is <dir>/windtrap-<hash>.<f.ext>. <dir> is the data_dir of the build directory of exe, or the standalone_data_dir of the current directory when exe lies below none. <hash> is the hexadecimal MD5 of exe_identity ~exe. It is one file for each executable, for a format whose writer replaces its file on every run.

output_dir f ~exe is output_file f ~exe without its extension. It is one directory for each executable, for a format whose every run keeps a file of its own (see write_new_file).

The type for the errors of reading a file, the same for the two formats.

pp_error f ppf e formats one line on e for a person, in the words of f. The message is not stable enough for a program to match.

warn fmt ... writes windtrap: warning: , the message that fmt formats and a newline on standard error, and flushes it. Control bytes are written as they are.

read_file path is the contents of the file at path, read in binary mode. It is Error (Unreadable _) when the file cannot be opened or read, and Error (Corrupt _) when the file shrinks while it is read.

write_file path data writes data to path, and creates the directory of path if needed. It writes a temporary file beside path and renames it over path, so a reader never sees a partial file. Of two writers at the same time, the last rename wins and the file is whole. Raises Sys_error if the file cannot be written, and leaves no temporary file then.

write_new_file dir ~prefix ~ext data writes data to a new file <prefix><token>.<ext> in dir, through a temporary file and a rename as write_file does. It creates dir if needed and is the path of the new file. <token> is six hexadecimal digits that the creation of the temporary file reserves, so writers at the same time never share a name. Raises Sys_error if no name can be reserved in ten attempts, or if the file cannot be written.

add_header f buffer identity appends the magic line of f to buffer, and then the identity line when identity is given. Raises Invalid_argument, in a message that f.who prefixes, if identity.exe is empty or if identity.digest is not 32 lowercase hexadecimal digits. The magic line is already in buffer then.

The type for cursors: a position in an input string, which the readers advance.

Raised by the readers below, with a reason for a person.

parse_fail fmt ... raises Parse_error with the formatted reason.

start f ~path s is a cursor over s that stands after f.magic. It is Error (Unknown_format _) naming path when s does not begin with f.magic followed by whitespace or by the end of the input. An input that begins with windtrap-coverage-v30 is of another format, and the magic string alone is a valid start.

read_nat c what reads a decimal natural number after any whitespace. Raises Parse_error naming what if there is no number, if it is negative, or if it does not fit an int.

read_count c what is read_nat, bounded by the length of the whole input, the part already read included. It is for a count of items that each take at least one byte. Raises Parse_error naming what if the number is larger.

read_name c what reads a length-prefixed string: a natural number, one space, and then that many bytes, whitespace included. Raises Parse_error naming what if one of the three is missing.

read_word c what reads a maximal run of bytes that are not whitespace, after any whitespace. Raises Parse_error naming what at the end of the input.

read_identity c reads the identity line when the input, after any whitespace, starts with the three bytes exe. It is None otherwise, with c past that whitespace only. Raises Parse_error if the digest is not 32 lowercase hexadecimal digits, or if the path is malformed, truncated or empty.

finish c accepts the end of the input, after any whitespace. Raises Parse_error if anything else remains.