Rootbeer API

This header defines all of the publicly accessible APIs for Rootbeer plugins. These can be called within a native Rootbeer plugin to interact with the core Rootbeer revision system. See src/plugins/rootbeer_core for an example of a plugin.

Defines

RB_OK

The return code for a successful operation.

RB_ULIMIT_EXTFILES

The return code when the maximum external files limit is reached.

RB_ULIMIT_TRANSFORMS

The return code when the maximum plugin transforms limit is reached.

RB_ENOENT

The return code when a file or directory does not exist.

RB_EACCES

Typedefs

typedef struct rb_ctx_t rb_ctx_t

Rootbeer context structure. This is an opaque pointer to the internal Rootbeer context. See rb_ctx_t for more details.

Functions

int rb_track_ref_file(rb_ctx_t *ctx, const char *path)

Registers the provided filepath as a reference file. Reference files are kept track of as “imported” files in the revision system. For example, rb.link_file() uses this to track the source files for links.

Parameters:

  • ctx – The Lua context to track the file in.

  • path – The ABSOLUTE path to the file to track.

Returns:

0 on success, or a negative error code on failure. TODO: Make this use absolute paths instead of relative paths.

int rb_track_gen_file(rb_ctx_t *ctx, const char *path)

Registers the provided filepath as a generated file. Generated files are those that are created by a plugin at runtime. For example, rb.link_file() uses this to track destination files for links.

Parameters:

  • ctx – The Lua context to track the file in.

  • path – The ABSOLUTE path to the file to track.

Returns:

0 on success, or a negative error code on failure.

FILE *rb_open_intermediate(rb_ctx_t *ctx, const char *id)

Opens a handle to an “intermediate file”. Intermediate files are used to store temporary data that is not meant to be kept long-term. They can be looked up by their ID at a later time.

Parameters:

  • ctx – The Lua context to open the intermediate file in.

  • id – The ID of the intermediate file to open.

Returns:

A file handle to the intermediate file, or NULL on failure.

const char *rb_get_intermediate(rb_ctx_t *ctx, const char *id)

Retrieves the content of an intermediate file by its ID. This function reads the content of the intermediate file and returns it as a string.

Parameters:

  • ctx – The Lua context to retrieve the intermediate file from.

  • id – The ID of the intermediate file to retrieve.

Returns:

A pointer to the content of the intermediate file,

rb_ctx_t *rb_ctx_from_lua(lua_State *L)

Fetches the current Rootbeer context from the Lua state. We store the context in Lua via a light userdata pointer, whic allows us to fetch it easily from the Lua state and use it flexibly across the project. To identify the context, we use this fetch function as the ID for the data.

Note

This function will panic if the context is not set in the Lua state.

Parameters:

L – The Lua state from which to fetch the context.

Returns:

A pointer to the Rootbeer context.