The Ape of Thoth
A Thelemic Text Daemon
Do what thou wilt shall be the whole of the Law
Consulting the Oracle
The heart of the 'Ape of Thoth' (APE for short) is a CGI script. The script accepts
requests in either POST or GET mode. This means that your page can access the
script with an HTML form, or directly from the URL (which would be especially
useful if you want to provide a search link without the use of a form).
The script and all supporting files reside (for now) in the following place:
Normally, the script is invoked with a text file name and a command. For
example, the following URL will render a random verse from the Book of the Law:
In this case, the text file is 'liber220' and the command is 'random'.
There is an index.html file in the Hanuman directory which demonstrates the
major features of the script. The script is activated with a command after
the script name in the URL. Calling the script with no command and no text
file name causes the file 'index.html' to be sent to the requestor.
Selecting a range of verses
A sub-set of verses in any given text may be singled out for viewing and/or
analysis. To select a range, simply add a colon and a single verse number or
a pair of verse numbers separated by a hyphen. For example, if we wanted only
verses 5 through 10 of Liber Librae, we could use the URL:
The range may be specified in any of the following ways:
Note that if you specify a range for a multi-chapter document or for the
'All Documents' document, the specified range (or as much of that range as
exists) will be returned for each chapter or document.
||Selects the single verse numbered 'n'|
||Selects all verses up to 'n' |
||Selects all verses from 'n' onward|
||Selects all verses from 'n' to 'm'|
Be aware that the time required to filter the selected verses from the
document makes the resulting page load slightly slower so please only use
the range selector when you have a good reason to view less than all the
available verses of the text.
Links within documents
Each chapter title and each verse number is tagged as a hyperlink. The primary
reason for this is to make the verse stand out in the text. For the most part,
the links point to the verse itself in the complete document. If you requested
a range of verses or searched a document, these links can be used to jump to
the selected verse in the complete document.
The chapter and verse links in the individual chapters of multi-chapter texts
point to the corresponding locations in the complete text. This allows the user
to see an entire chapter 'in context'. The verse link for the random verse
selection page (and for any search performed across multiple texts) point to
the individual verse in the book or chapter from which it came. To see a more
complete selection of text, follow the hyperlink shown for that verse.
The links shown for each word in a concordance page invoke a search for the
word selected across the same text used to generate the concordance. The
search is performed for whole words only and in the same case sensitivity mode
as was the original concordance request.
The one exception to the linking scheme occurs between the documents known as
The Book of the Law and The Book of the Inlaws. The latter is a parody of the
former and the links in each of these documents point to the corresponding
verse in the other. If you follow one of these links and you really wanted the
original verse, just select the link in the corresponding verse and you're
back in the original document. Neat, eh?
Making GET/POST requests
Additional information is often needed by the script in order to carry out
the request. This information may be passed as part of the URL by appending
a question mark (?) and a series of fields in any order. The following
fields are defined:
Notice that the text file name may be specified as a field. This is so that
the specific text to be searched can be selected as part of a form on the
referring page. The 'input=[filename]' field is only used when the file is
not specified as part of the URL, as in the following example (which will
render the same result as the example above):
Because of the alternate ways in which data may be supplied to the script,
conflicts can arise. The following rules are applied when data elements overlap:
||Specify the text file to search|
||Specify the word(s) or phrase for which to search|
||Specify 'all words', 'any word', 'no words', or 'whole phrases'|
||Specify 'case sensitive' or 'case insensitive'|
||Specify 'whole words only' or 'any match'|
||Split hyphenated words (concordance only)|
||Filters the 'dd' and 'dt' tags for a more compact output|
||Indicates the number of the first verse to scan|
||Indicates the number of the last verse to scan|
||Indicates a range of verses to scan (either 'n' or 'm' may be omitted)|
- If an input text is given in the URL path, it overrides 'input=[filename]' field.
- If a 'range=[n-m]' field is given, it overrides both the 'start=[n]' and
The simplest command is the 'null' command (that is, no command at all). In
this case, the script will return the complete text of the named document:
Another simple command is the 'random' command. This command returns one
verse at random from the selected text:
The 'quote' command is similar to the 'random' command except that only
the verse itself is returned and the hyperlink has the full URL of the APE
Home Page. The only real use for this command is to add a random Holy Book
quote to another web page using Server-Side
The 'concord' command produces a list of all the words which occur in the selected text
and links each to the search command for that particular word:
More complex is the 'search' command. This command may be supplied several
optional fields to control the search algorithm. If the 'search=' field is
not supplied, the effect is the same as with the 'null' command (that is,
the entire text is returned). Assuming the search text is 'text' and case
sensitivity is turned on you could use:
Following is a list of the documents supported as of the writing of this
description. The list is always growing and it pays to check the
'index.html' file to see the latest additions.
In addition, there are three special 'pseudo-documents' provided. The file
called 'liber0' has the complete contents of all the documents supported
by the APE. The file 'liber00' has all the documents except Liber Call
Me Al and 'liber000' has only the A\A\ Class A documents.
||Liber B vel Magi|
||Liber Liberi vel Lapidis Lazuli, All|
||Liber Liberi vel Lapidis Lazuli, Prologue|
||Liber Liberi vel Lapidis Lazuli, Chapter I|
||Liber Liberi vel Lapidis Lazuli, Chapter II|
||Liber Liberi vel Lapidis Lazuli, Chapter III|
||Liber Liberi vel Lapidis Lazuli, Chapter IV|
||Liber Liberi vel Lapidis Lazuli, Chapter V|
||Liber Liberi vel Lapidis Lazuli, Chapter VI|
||Liber Liberi vel Lapidis Lazuli, Chapter VII|
||Liber Porta Lucis|
||Liber Causae, All|
||Liber Causae, Preliminary Lection|
||Liber Causae, History Lection|
||Liber Cordis Cincti Serpente, All|
||Liber Cordis Cincti Serpente, Chapter I|
||Liber Cordis Cincti Serpente, Chapter II|
||Liber Cordis Cincti Serpente, Chapter III|
||Liber Cordis Cincti Serpente, Chapter IV|
||Liber Cordis Cincti Serpente, Chapter V|
||Liber Stellae Rubeae|
||Liber Liber Astarte|
||The Book of the Law, All|
||The Book of the Law, Chapter I|
||The Book of the Law, Chapter II|
||The Book of the Law, Chapter III|
||Liber Os Abysmi|
||Liber Call Me Al, All|
||Liber Call Me Al, Chapter I|
||Liber Call Me Al, Chapter II|
||Liber Call Me Al, Chapter III|
How to link the Oracle to your page
The APE is best accessed via an HTML form. However, the GET method
is also supported which means that everything can be specified as part of the
URL. However, if you want the user to be able to specify the search string
and to control the searching, use a form similar to the following:
When a request is made to the APE, the filename is
used to determine which HTML file to open. The extension '.html' is added
to the file name passed in the URL and this file is read by the script. The
HTML file can have any text or formatting within it. In addition, it should
contain one or more 'pseudo-comments' which control where and how the text
of the search should be inserted.
The typical HTML file will contain at least one 'foreach..end' pseudo-comment
pair which specifies the data file to be read:
...Modified HTML goes in here...
When the script reads this sequence, it opens the file specified by 'filename'
and proceeds to search the verses contained therein according to the options
selected. For each matching verse, it emits the HTML code contained in the
'foreach...end' pair, with certain substitutions. For each 4-letter keyword
which appears in the format %keyw%, the appropriate information corresponding
to the verse in question is printed instead. The possible keywords are:
Multiple lines of HTML may be placed between the 'foreach' and the 'end' but
both comment tags must appear at the start of a new line and must not be
followed by other text or HTML tags.
||the name of the data source file|
||the verse number of the verse|
||the name of the data source file, a colon, and the verse number|
||the verse number (or '*' for non-numbered verses)|
||the title of the document plus 'utag' above|
||the text of the verse itself|
||the word from the concordance list (concord only)|
||the case sensitivity switch (concord only)|
An additional pseudo-comment may be used to specify HTML text to be emitted
when no data file lines satisfy the match. This HTML is not subject to the
same substitutions, as there is no verse involved.
...HTML to print a single verse...
...HTML to print if no verses match...
If the 'filename' is omitted, then the file name originally passed in the URL
is used instead. This is important for the 'random' command, which always
uses the file 'random.html'. In this case, the actual filename which will be
searched is not known when the 'random.html' file is created.
At the top of each HTML file is a
tag which specifies the URL of the directory in which the APE script and
data files reside. This is required in order for the links on the document
verses to function correctly and be changed if the script is moved to another
location. The data files must remain in the same directory as the script.
The data files containing the text to be searched must conform to a specific
format. Each 'verse' of the text must appear on a separate line and there may
be no blank lines in the file. Each line consists of a verse number (or
letter), a right paren, and the text of the verse, thus:
1) The text of the first verse
2) The text of the second verse
3) The text of the third verse
In order to make the file maintainable, a single 'line' of text may be
divided into multiple physical lines by appending the backslash (\) character
to the end of each line which is to be continued on the next physical line.
For example, the following example consists of three 'lines' of text:
1) The text \
of the first line
2) The text \
of the second line
3) The text \
of the third line
A data file may include other data files. This would be used to create a
single text database for searching multiple documents without having to
duplicate the actual text of the documents. To include the text from another
data file, use the following line:
where 'filename' is the name of the file to be included and 'tag' is the name
of the document in human-readable format. Included lines are displayed in a
slightly different manner from other text lines. The human-readable 'tag' of
the file is prepended onto the verse number in order to identify in which of
possibly several documents the verse in question was found.
The script has an access log feature built-in. If a file named 'logfile' is
present in the directory when the script is run, information regarding the
currrent invocation will be appended onto this file. To disable the logging,
simply delete or rename the log file.
The script can also notify the owner (or anyone with an e-mail address) of
each access. This is to be used primarily for debug. If a file named 'logmail'
exists, the file is read and each line is assumed to be an e-mail address.
The command and file name of the request are sent to each address listed.
There are two processing optimizations that the script will take, if available.
The first involves the removal of the backslash (\) continuation characters
from the source files. If the requested file is not found in the directory
from which the script is run, but a copy is found in a sub-directory named
'source', the file in 'source' is assumed to contain continuation characters
and a one-verse-per-line copy is written into the current directory. This,
in practice, saves little in the way of processing time and consumes twice
the disk space, since there are then two copies of the data. This may be
disabled by moving the sources to the directory containing the script and
deleting the 'source' directory.
The second optimization saves quite a bit more processing time, but only for
accesses of entire documents. Whenever a whole document is accessed (that is,
no search/random/concord command and no range specified), the directory
named 'compiled' is searched. If the document in question is present, it is
returned to the user. If not, the script will write a plain HTML copy of the
entire document into that directory and then return it to the user. This may
be disabled by deleting the 'compiled' directory.
Using server-side includes
If you want to have a random quote-of-the-day on your web page, you can use
a trick called Server-Side Includes (if, of course, your ISP supports them).
Essentially, you must make a 'quote' request of the APE, save the output to
a file, and include the file in your HTML code. If you have the Lynx browser
available on your system, the request is easy:
lynx -source http://larabell.org/Hanuman/Hanuman.cgi/liber220/quote
will fetch a quote from The Book of the Law. Redirect that to a file and
you're half-way there. (If you run the fetch command as a cron job once
per day, the quote will change automatically).
Now, assuming you have SSI capability, you can include the following in any
Of course, it is also possible to put the lynx command directly into the
'.shtml' include tag in order to get a random verse every time you access
the page in question. However, please don't do this on high-volume pages, as
the APE is runnig under a bandwidth quota and anyone abusing the system will
be locked out.
The 'Ape of Thoth' script was written by