The Book of Conworlds Scan Processing System
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 

9.3 KiB

Detailed documentation

Configuration file

The configuration file consists of a single Lisp list with three different types of form. Semantically, they represent things that are unlikely to change throughout the runtime of the program. It is located in $XDG_CONFIG_HOME/bocproc/entities.lisp.

setting form

  (setting KEY &rest VALUE)

Simple key-value settings are created using this item.

tag form

  (tag NAME (&rest SUPERTAGS [&TAGLESS &rest UNINHERITED-SUPERTAGS])
       &rest COLUMNS &allow-other-keys)

Defines a tag, which is an attribute which may be attached to a given page for easier searching. The tag is named NAME and inherits the attributes from tags listed in SUPERTAGS. It also "belongs" to tags listed in UNINHERITED-SUPERTAGS but does not inherit their attributes (this is useful in searching, where groups of tags may be defined without specifically having attributes for inheritance.) These are separated with the symbol &tagless. COLUMNS specify the individual attributes, which may or may not have defaulting behaviour. The property list must have keywords as keys and any readable object as values.

Further semantics are defined in /isoraqathedh/bocproc/src/branch/master/doc/%2AOn%20tags.

series form

  (series NAME
          (; PAGE-NUMBER-DEFINITION
           &rest (; PAGE-NUMBER-SPECIFICATION
                  SPEC-NAME MIN &optional MAX))
          DIRECTORY-TEMPLATE
          FILENAME-TEMPLATE
          &optional INPUT-FILE-NAME-REGEXP)

Defines a series, which is a particular list of pages that together form a stack of notebooks with a consistent theme. In a series, each individual page has a page number, which is a list of numbers bounded by the values in PAGE-NUMBER-SPECIFICATION. Preceded by the series name, the overall list, called a page code, uniquely identifies a page within this system. An example of a page code is (boc 37 2 1).

The series is named NAME. The page numbers within a page is restricted by the values in PAGE-NUMBER-DEFINITION as such:

  • There are exactly as many page numbers in a page code as there are elements in PAGE-NUMBER-DEFINITION.

  • Each position is named according to the first SPEC-NAME.

  • The names can be any keyword. However, if a keyword that is used by the package local-time to represent a time component in local-time:format-timestring is used to name a position, then the value of that position is used to represent a particular date associated with the page.

    This special provision may be ignored when reading the database, but is essential when writing it.

  • The number in a particular position must be at least MIN in the corresponding PAGE-NUMBER-SPECIFICATION.

  • If it exists, the number can be at most MAX in a similar manner. Otherwise there is no upper limit.

DIRECTORY-TEMPLATE and FILENAME-TEMPLATE are two lists that define the canonical file name for the page. The former is a list of one or more FILENAME-FRAGMENT-COLLECTION, while the latter is exactly one of these. A FILENAME-FRAGMENT-COLLECTION is a list of the following objects:

  • A string, which represents itself;

  • A keyword, which represents a parameter to be substituted with a string at a later date;

  • A list starting with the symbol :date, which is then followed by a list that is usable in local-time:format-timestring

  • A list starting with any other keyword, followed by a plist with keyword keys and readable values, which are considered "arguments" to the first keyword

The configuration file does not specify how these elements are to be interpreted otherwise.

Database file

The database file consists of a single Lisp list with four different types of form. Semantically, they represent things that are to be managed by the BOCPROC system. This file is to be located by the user.

The file must be encoded in UTF-8. Its first line must begin with the following characters, which serve to identify the file as a bocprocdb file:

#:|bocprocdb|

It formally does not mean anything, but it is patterned in such a way so that Lisp readers can read it as a symbol.

bpd-version form

  (bpd-version ATTACH/DETACH &rest VERSION-NUMBERS)

Should be the first element of the vector. Should only be provided once.

Identifies the version of the form. This is currently ignored, but allows future compatibility.

ATTACH/DETACH is either the keyword :attach or :detach, and defines whether or not tag and series forms are also located in the file. This is currently not supported, but in the future, it will be used as a way to create self-contained database files.

root form

  (root ROOT)

Specifies a directory where all relative pathnames in the vector are based on. Should be provided once or not at all. If not provided, assume it to be in the directory of the file.

ROOT is an absolute pathname or its namestring.

ignore form

  (ignore SERIES &rest IGNORED-NUMBERS)

Defines a range of pages to be ignored.

The length of IGNORED-NUMBERS must be less than or equal to the number of components in the corresponding SERIES's PAGE-NUMBER-DEFINITIONS. IGNORED-NUMBERS together form a sub-sequence from the left of a valid page number. All pages that have a page code which matches this sub-sequence is considered ignored.

entry form

  (entry PAGE-CODE &rest KEYS &key &allow-other-keys)

Represents an entry to be examined by the system. PAGE-CODE is the page code and serves as the name of the entry. KEYS is a property list. Other than being a property list, the database file does not impose any further restriction on what it contains. This will be up to the application to decide.

On tags

Conceptually, the tag list is a both a tree and a table; each tag defines a row in a table, and the tags have an inheritance table.

The columns in each table are the attributes of the tag. Take for example the following tag list:

  (tag foo ()
       :type :edible)
  (tag bar ()
       :type :visitable
       :maximum-weekly 2)

  (tag apple (foo)
       :colour "red"
       :maximum-daily 2
       :maximum-weekly 10)
  (tag orange (foo)
       :colour "orange"
       :maximum-daily 3
       :maximum-weekly 12)
  (tag horse-and-feather (bar)
       :location "East End")
  (tag trip-to-jerusalem (bar)
       :location "Nottingham"
       :maximum-weekly 1)
  (tag chocolatier (foo bar)
       :maximum-daily 1)

This defines a tag table something along the lines of this:

/ < <r> <r> >
Tag Type Colour Maximum-Daily Maximum-Weekly Location
foo Edible
bar Visitable 2
apple Edible red 2 10
orange Edible orange 3 12
horse-and-feather Visitable 2 East End
trip-to-jerusalem Visitable 1 Nottingham
chocolatier Edible, Visitable 1 1

The tag inheritance causes the items in italics to be filled in. Notice that this is done vertically, with values only moving up and down the table.

Values can also spread left and right across the table, if the user of the tags require it. For instance, we might require say that :maximum-daily inherits :maximum-weekly, so the underlined values are then filled in:

/ < <r> <r> >
Tag Type Colour Maximum-Daily Maximum-Weekly Location
foo Edible
bar Visitable 2 2
apple Edible red 2 10
orange Edible orange 3 12
horse-and-feather Visitable 1 2 East End
trip-to-jerusalem Visitable 1 1 Nottingham
chocolatier Edible, Visitable 1 1

Additionally, notice the type of chocolatier has a conflict (either :edible or :visitable) and in this case the resolution is that they are appended together. Again, it is up to the user of the tags to decide whether the tags should be appended together, become some other mixed value, or simply become unset altogether when there is a conflict.