Script Index

/var/lib/sorcery/modules/libcodex

A grimoire is a book containing one or more spells. A codex is a collection of one or more grimoires. There are functions for listing the available grimiores, listing spells in a grimoire, listing sections in a grimoire, etc. Note: Each of the functions that returns a spell, section, or grimoire returns the full path. Functions that explicitly return a spell I or section I do not return the full path.
grimoires
This section contains some notes on grimoires.
Grimoire Layout
The codex functions expect each grimoire to be a directory. Each directory entry in a grimoire directory is considered to be a section. All directory entries in a section are considered to be a spell if they included an executable file named F

.
Multiple grimoires
Multiple grimoires are specified by setting entries in the I array. For example, to set two additional grimoires, you would put something like the following in your local SMGL grimoire file (F). 
GRIMOIRE_DIR[1]=/path/to/alternate/grimoire
GRIMOIRE_DIR[2]=/path/to/other/alternate/grimoire
Grimoires are processed/searched in increasing order starting at index 0. The SMGL configuration file provides the value for the default grimoire as I or simply I. The following two lines show how to reorder the default grimoire so that it's not searched first (in this example it will be searched second). 
GRIMOIRE_DIR[1]=$GRIMOIRE
GRIMOIRE_DIR[0]=/path/to/grimoire/to/search/first
There is no limitation on the number of grimoires that can be specified. It is also possible to add and remove grimoires using the codex_add_grimoire and codex_remove_grimoire functions. Copyright 2002 by the Source Mage Team

Copyright

Synopsis

Set of functions for dealing with a library of grimoires (spell books).

function codex_canonicalize_grimoire_name()

Parameters:

  • $1: grimoire
  • $2: lookup (optional)
  • $3: variable to set (optional)

Returns:

  • 0 if grimoire can be canonicalized

Description

Outputs a grimoire in canonical form (full path) if lookup equal to "lookup" look up the grimoire name else build the grimoire name from $CODEX_ROOT/$grimoire CODEX_ROOT is the default grimoire location NOTE: one can specify partial paths

function codex_find_grimoire()

Parameters:

  • $1: grimoire name, or path to one
  • $2: variable name, is set to the matching grimoire (optional)
  • $3: variable name, is set to the matching grimoire's index (optional)

Returns:

  • 0 there is a grimoire
  • 1 there is no grimoire

Stdout

the grimoire's path

Description

NOTE: one can specify partial paths such as codex/stable 

example1:
codex_find_grimoire test; echo "returned $?"
/var/lib/sorcery/codex/test
returned 0
example2:
codex_find_grimoire sorcery/codex/stable; echo "returned $?"
/var/lib/sorcery/codex/stable
returned 0

function codex_add_grimoire()

Parameters:

  • $1: grimoire
  • $2: [position]
  • $3: [overwrite]

Description

Adds the specified grimoire to the list of grimoires. If no position is given, the grimoire is added to the end of the list. Position is 0 based. Adding a grimoire to position 0 places it as the first grimoire in the list, and moves all other grimoires down one spot, unless [] is set to "overwrite". This function does not currently delete duplicate entries.

function codex_remove_grimoire()

Parameters:

  • $1: grimoire

Description

Removes the specified grimoire from the list of grimoires.

function codex_remove_duplicates()

Parameters:

  • None

Description

Removes duplicate entries from the GRIMOIRE_LIST. This parses from 0 on up, and leaves only the first instance of a grimoire found. All others are removed. Then reloads the list

function codex_set_grimoires()

Parameters:

  • $1: grimoire name | grimoire dir ....

Description

Unsets the list of grimoires that existed before the call, then sets the lists of grimoires to be equal to the list of grimoires in the argument list. Grimoire names need not be canonicalized

function codex_get_all_grimoires()

Parameters:

  • None

Stdout

all grimoires in the codex.

function codex_is_local()

Parameters:

  • $1: grimoire-name

Description

returns true if the grimoire is set local, false otherwise.

function codex_find_section_by_name()

Parameters:

  • $1: section
  • $2: variable to set (optional)

Returns:

  • 0 if section is found
  • 1 if section is not found

Stdout

full path to the section

Description

Given a valid section name, this function lists the full path to the section. If an invalid section name is provided, nothing is listed.

function codex_get_all_section_names()

Parameters:

  • None

Stdout

all section names from all grimoires.

function codex_get_all_sections()

Parameters:

  • $1: grimoire-pathes (optional)

Stdout

all sections from all grimoires or only from the specified grimoires.

function codex_get_section_names()

Parameters:

  • $1: grimoire

Stdout

Lists all section names in the specified grimoire.

Description

Relies on a wider-scope function codex_get_sections.

function codex_get_sections()

Parameters:

  • $1: canonicalized grimoire names

Stdout

Lists all sections in the specified grimoire directories.

function codex_is_directory_a_spell()

Parameters:

  • $1: full directory

Returns:

  • 0 if the specified directory is a spell directory.
  • 1 otherwise

function codex_does_spell_exist()

Parameters:

  • $1: spell
  • $2: [spell ...]

Returns:

  • 0 if all the specified spells exist
  • 1 othterwise

function codex_find_spell_by_name()

Parameters:

  • $1: spell name

Stdout

spell name

Description

Given a valid spell name, this function lists the full path to the spell. If an invalid spell name is provided, nothing is listed.

function codex_get_spells_in_section()

Parameters:

  • $1: path/section

Stdout

spells

Description

Lists full paths to spells in the specified section. Nothing is listed if the section doesn't include any spells.

function codex_get_spell_names()

Parameters:

  • $1: path/section

Stdout

spells

Description

Lists all spell names in the specified section. Nothing is listed if the section doesn't include any spells.

function codex_get_all_spells()

Parameters:

  • $1: grimoire-pathes (optional)

NOTE

This should be fixed so only the first of duplicate spells are listed.

Stdout

spells

Description

Lists all spells in all grimoires or only from the specified grimoires. Nothing is listed if no spells exist in any of grimoires.

function codex_get_spell_section()

Parameters:

  • $1: spell name

Stdout

spell name

Description

Lists the section of the given spell name. Nothing is listed if there are no spells with the given name.

function codex_get_spell_section_name()

Parameters:

  • $1: spell name

Stdout

section name

Description

Given a spell name, this function lists the section name. If there are no spells with the given name, nothing is listed.

function codex_clear_current_spell()

Parameters:

  • None

Globals

GRIMOIRE SECTION SECTION_DIRECTORY SPELL SPELL_DIRECTORY SCRIPT_DIRECTORY SPELL_DESCRIPTION VERSION SHORT UPDATED SOURCE WEB_SITE ENTERED MAINTAINER MD5 LICENSE

Description

Unets all these global variables.

function codex_set_current_spell()

Parameters:

  • $1: spell directory

Globals

All vars set in a spell

Description

Sets the GRIMOIRE, SECTION, SECTION_DIRECTORY, SPELL_DIRECTORY, SCRIPT_DIRECTORY global variables for the given spell directory. Assumes the directory passed in is a valid spell directory.

function codex_set_current_spell_quick()

Parameters:

  • None

Description

Load just the very basics for a spell, skip build api, libcompat and other debug stuff. Intended for use in tight loops.

function codex_get_spell_paths()

Parameters:

  • None

Description

Setup the various spell paths associated with a spell without loading it.

function codex_set_current_spell_by_name()

Parameters:

  • $1: spell name

Returns:

  • 1 if the given name is not a spell.

Description

Sets the GRIMOIRE, SECTION, SECTION_DIRECTORY, SPELL_DIRECTORY, SCRIPT_DIRECTORY global variables for the given spell name.

function codex_find_spell_provides()

Parameters:

  • $1: spell name

Description

Returns the features a spell is a provider off. Example, firefox: GECKO, GRAPHICAL-WEB-BROWSER, WEB-BROWSER, NS-PLUGIN-COMPATIBLE

function find_providers()

Parameters:

  • $1: category/service

Stdout

spelllist

Description

First argument is a category of spell. Returns a list of spells that match that category. For example, C returns evolution,althea,mutt,etc. This will list spells exactly once, exiled spells are not listed. This also takes into account grimoire ordering. A spell must provide the category in the first grimoire the spell is seen in (because that is the only one that will be cast) otherwise it is not listed.

function codex_cache_spell_lookup()

Parameters:

  • $1: spell name
  • $2: grimoire-path
  • $3: [grimoire-path ...]

Returns:

  • 0 Spell found
  • 1 Spell not found

Description

Searches the indicies of the specified grimories for a spell. This will return only the first match found.

function codex_check_cache()

Parameters:

  • $1: grimoire-path

Stdout

error if cache doesn't exist after creation

Description

Checks that the cache exists. if it doesn't exist, make it. If it still doesn't exist, the barf an error

function codex_create_cache()

Parameters:

  • $1: [grimoire-path]

Description

Creates the cache/index for the specified grimoire, or all if none is asked for.

function codex_create_in_memory_cache()

Parameters:

  • None

Description

Create in-memory spell lookup table for named grimoires.

function codex_create_in_memory_cache_all()

Parameters:

  • None

Description

Creae in-memory spell lookup table for all known grimoires.

function codex_find_in_grimoire()

Parameters:

  • $1: grimoire-path
  • $2: file-name

Stdout

file names

Description

Prints every file matching file-name in grimoire

function codex_list_provides()

Parameters:

  • $1: grimoire-path

Stdout

provides spell

Description

Lists all providers in grimoire in the form of "provides spell" for instance:
shell /home/martin/p4/grimoire/shell-term-fm/sash

function codex_create_keyword_cache()

Parameters:

  • $1: grimoire-path

Description

Creates keyword index

function codex_create_version_cache()

Parameters:

  • $1: grimoire-path

Description

Creates the version index, which additionally includes the other queuing factors - patchlevels and UPDATED. Multiversioned spells will a dummy entry. Persistent variables are ignored.

function codex_does_service_exist()

Parameters:

  • $1: servicename

Returns:

  • 0 if service exists
  • 1 otherwise

Description

checks if servicename exists.

function codex_find_spell_or_section_by_name()

Parameters:

  • $1: spell or section name

Returns:

  • 0 if the passed argument is a spell name or a section name.
  • 1 otherwise

Globals

CODEX_FOUND_SECTION CODEX_FOUND_SPELL

Description

CODEX_FOUND_SECTION is set if section was found CODEX_FOUND_SPELL is set if a spell was found

function codex_get_spell_description()

Parameters:

  • $1: spell directory

Stdout

spell description

Description

Echos the long description of the given spell. Returns an empty string if the directory is not a valid spell.