This section gives an overview of the Rarian Library. It outlines how to harness the power of Rarian and gives an overview of the available functions.
Note: Rarian is currently API-unstable. You are advised to explicitly check and use exact versions of Rarian
You can include the library in your application by using pkg-config to set the correct include and lib flags. The name to check for is "rarian". You should check for exact versions at this stage as Rarian API is liable to change in future releases.
Alternatively, you can set the cflags and libs yourself. The correct include path is ">prefix</include/rarian" and the library name is "rarian".
Rarian is currently split into three parts:
which gives access to the three different forms of documentation available to Rarian. Each of these is discussed in the relevant section here.
Each of the three "sections" of LibRarian share commonalities. The primary one is initialisation. In all three cases, initialisation happens implicitly on the first call requiring access to the internal list of documents. This means the documents should always be available when calling into the functions.
Main documents are defined by anything with an equivalent "scroll" file. This documentation can be of any form and Rarian can provide lists of the documentation. The scroll files are picked up from $XDG_DATA_DIRS/help and form the basis for most of Rarian.
The following documents can be accessed by including the "rarian.h" file.
Functions returning meta-data do so in a struct, the RrnReg. The definition for this struct looks like:
struct _RrnReg
{
char *name;
char *uri;
char *comment;
char *identifier;
char *type;
char *icon;
char **categories;
int weight;
char *heritage;
char *omf_location;
char *ghelp_name;
char *lang;
RrnSect *children;
};
Most of these fields are self-explanatory and match up with the fields in the scroll files. The ones that do not are described below:
Note: The returned structure must never be freed.
rrn_for_each (RrnForeachFunc funct, void * user_data)
Iterates through each available document in turn and calls funct for each. If funct returns FALSE, iteration is stopped immediately.
void rrn_for_each_in_category (RrnForeachFunc funct, char * category, void *user_data)
Iterates through each document in category and calls funct for each. If funct returns FALSE, iteration is stopped immediately.
The prototype of RrnForeachFunc looks like:
typedef int (* RrnForeachFunc) (void * reg, void *data);
The void *reg will be a pointer to the RrnReg for the entry as described above. The void *data parameter is the user_data parameter passed into the for-each function.
RrnReg * rrn_find_entry_from_uri (char *uri)
Finds the relevant entry from the uri. This simply compares the uri to the uri field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. If no match is found, NULL is returned.
RrnReg * rrn_find_from_name (char *name)
Finds the relevant entry from the name. This simply compares the name to the name field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. If no match is found NULL is returned.
RrnReg * rrn_find_from_ghelp (char *ghelp)
Finds the relevant entry from the ghelp. This simply compares the ghelp to the ghelp_name field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. The passed in parameter ghelp must have the "ghelp:" removed from the front of the URI. If no match is found, NULL is returned.
Rarian provides several miscellaneous functions in this sections. These are described here.
void rrn_set_language (char *lang_code)
By default, Rarian will set itself up using the $LANGUAGE environment variable. You can override this behaviour by calling this function with lang_code set to the desired language. Multiple language codes can be specified using colon-delimiting. When called, this function will re-initialise the internal list of documents to the desired language.
void rrn_shutdown ()
This function shuts down Rarian, freeing any used memory. This is generally not needed, though may be useful for low-memory situations when it is known that Rarian will not be necessary again.
Rarian provides access to installed man pages on the system. This functionality can be accessed by including the "rarian-man.h" file.
As with the main documents, functions return structs containing meta-data, the RrnManEntry struct, as described below:
typedef struct _RrnManEntry {
char *name;
char *path;
char *section;
char *comment;
} RrnManEntry;
Each of these fields are self-explanatory.
void rrn_man_for_each (RrnManForeachFunc funct, void * user_data)
This function iterates through all man pages and calls funct for each one. If funct returns FALSE, iteration is stopped immediately.
void rrn_man_for_each_in_category (char *category, RrnManForeachFunc funct, void * user_data)
Iterates through each man page within category and calls funct for each one. If funct returns FALSE, iteration is stopped immediately. Category names can be found by calling rrn_man_get_categories, described below.
The prototype for the RrnManForeachFunc is:
typedef int (* RrnManForeachFunc) (void * reg, void *data)
where reg is a pointer to the RrnManEntry and data is the user_data passed in to the for-each function.
RrnManEntry *rrn_man_find_name (char *name, char *sect)
Locates the man page entry with the name name and returns the relevant RrnManEntry. If sect is non-NULL, only entries in sect will be considered. If no entry is found, NULL is returned.
char **rrn_man_get_categories (void)
Returns an a list of char *s which describe the categories available in Rarian. The final entry in the list is NULL
void rrn_man_shutdown ()
Shuts down and frees all memory used by the man page section of Rarian.
Rarian provides access to info pages available on the system by parsing the info "dir" file to gather the available documents. All functions to handle info meta-data can be accessed by including the "rarian-info.h" file. Functions returning meta-data return a RrnInfoEntry struct, which is declared as:
typedef struct _RrnInfoEntry {
char *name;
char *shortcut_name;
char *base_filename;
char *base_path;
char *section;
char *doc_name;
char *comment;
RrnInfoCompression compression;
char *category;
} RrnInfoEntry;
The elements are described as:
Rarian provides a guess at the compression used for the info files in the "compression" field of the RrnInfoEntry struct. This can be one of the following enum (defined in rarian-info.h)
typedef enum _RrnInfoCompression {
INFO_ENCODING_NONE = 0,
INFO_ENCODING_GZIP,
INFO_ENCODING_BZIP,
INFO_ENCODING_UNKNOWN,
} RrnInfoCompression;
void rrn_info_for_each (RrnInfoForeachFunc funct, void * user_data)
Iterates over all info documents available and calls funct for each one. If func returns FALSE, iteration is stopped immediately.
void rrn_info_for_each_in_category (char *category, RrnInfoForeachFunc funct, void * user_data)
Iterates over all info documents available in the category category and calls funct for each one. If func returns FALSE, iteration is stopped immediately. A list of available categories can be found using rrn_info_get_categories described below.
The prototype for RrnInfoForeachFunc looks like:
typedef int (* RrnInfoForeachFunc) (void * reg, void *data)
where reg is the RrnInfoEntry associated with the document and data is the user_data element passed into the for-each function.
RrnInfoEntry *rrn_info_find_from_uri (char *uri, char *section)
Iterates through each entry in section and searches for the document matching uri. If section is NULL, all sections are searched. If no match is found, NULL is returned.
char **rrn_info_get_categories (void)
Returns a list of available categories. The list is NULL-terminated and must not be freed.
void rrn_info_shutdown ()
Shuts down and frees all memory used by Rarian info stuff.