Documentation for "b.py"

b.py is a small note taking program written in Python.

Usage: 
   b <file>[-<metadata>] <content>
   b %<command> <args>
   b @<pred> <subj> <obj>

It can be downloaded from b.txt (rename it to b.py), and comes under GPL 2 or later. Requires Python 2.2 to run, but may work (untested) on earlier versions.

Files and Items

Information is stored in a number of files, as items. An item is simply a line of text that contains metadata about when it was submitted, what its hash is, and so forther. Each line that is entered as a note to the program must be stored as an item in a file. To create a file, all you have to do is write to it. File names must match the regular expression [A-Za-z]+. For example, to create a file called "todo", and store a todo item in it, you could use the following command line:-

$ b todo "here's my first todo item!"
Item created in "notes" with uID "hy3"

(Note that the quote marks are only necessary in a shell where "!" has to be escaped, such as bash. They don't get passed to the program.) It is also possible to add extra program readable metadata information to the items that can be used later on. The "hy3" token at the end of the program status information printed is a unique ID for that item. It enables you to update the metadata or append to the item later on without having to type the entire date in. Unless tens of thousands of items are stored in a single file, IDs are typically three characters in length, and lower case alphanumeric for speed of entry.

Commands, and Reading Files

Once item(s) have been added to a file, you can manipulate and display them again using a command. All commands go by the following syntax: %commandname arguments. For example, the command to display all of the items in the "todo" file (along with an example result) is:-

$ b %cat todo
here's my first todo item (2003-04-15 14:38:59, hy3)

Note that even though the user didn't enter a date when they added that particular item, the date has been automatically saved and now displayed by the program. The program is configurable so that it doesn't have to display the date of items, but it always saves this information when an item is entered.

The "%cat" command is only used to print out the items in a file. There are plenty of other commands. Another useful one is "%ls", which lists all of the files that have so far been created. (Note how the commands roughly follow the names of their *nix counterparts—this just makes it easier on the author; the names are configurable). For example:-

$ b %ls
todo

This indicates that "todo" is the only file which has been created so far. Files are printed in alphabetical order on several different lines, a la "ls -1". For example:-

$ b notes "let's create another file!"
Item created in "notes" with uID "g53"

$ b %ls
notes
todo

No further options are available at this time. (@@ Globbing, etc.)

Item Metadata

The syntax for adding metadata to an item is much like that of flags in ordinary command line programs. There are a few attributes that one can use:-

 "D": marks the item as outdated, and removes it from the display
 "P": marks the item as being public, and world readable

It is possible to change the metadata of an item, the command for which will be discussed later. For now, to add metadata to an item whilst adding it to a file for the first time, take note of the following examples:-

$ b todo-P "this todo item is something that I'd like to share"

This saves the todo item with as a publically readable thingy.

File and Global Metadata

The syntax for adding metadata to a file or all files is: @property file value. This enables one to set, for example, various display options for files. For example, given the following file:-

$ b %cat test 
* a (2003-04-15 15:18:13, v72)
* b (2003-04-15 15:18:17, s27)
* c (2003-04-15 15:18:18, v3h)
* d (2003-04-15 15:18:20, gtb)
* e (2003-04-15 15:18:21, hds)

To display only the first three items of that file each time it is printed out, we can set the following metadata:-

$ b @show test 3

resulting in:-

$ b %cat test 
* a (2003-04-15 15:18:13, v72)
* b (2003-04-15 15:18:17, s27)
* c (2003-04-15 15:18:18, v3h)

Note also how each line is prefixed with an asterisk. This can also be set using a metadata attribute. To set the prefix to "*" for all items being displayed (i.e. in any file), simply use "#all" as the file name, and "prefix" as the property:-

$ b "@prefix #all *"

There are many other properties that can be set locally and globally, too.

Note that local file metadata overrides global metadata.

custom.conf

It's quite inconvenient to have to type long command lines (even a few characters more than necessary can be frustrating), and remember all the different command line configurations, so the commnd line is highly configurable. The program tries to read from a file named "custom.conf" in the main directory, which should contain a series of regular expressions that get applied in turn to any command lines entered to the program. For example, the following custom.conf file:-

r"^\.(.+?)$", "%cat \g<1>"

Means that one can enter things such as "$ b .notes" and have it be equivalent to "$ b %cat notes". Be warned that arbitrary code added to this file will be evaluated by Python; there are no security checks. A custom.conf file doesn't have to be present in the main directory for the program to work.

Other useful lines:-

r"^\.(.+?)$", "%cat \g<1>"
r"^del: (.+?) (.+?)$", "%setmeta \g<1> \g<2> D a"
r"^@@ (.+?)$", "todo \g<1>"
r"^done: (.+?)$", "%setmeta todo \g<1> D"
r"^sort: (.+?) (.+?)(?: (.))?$", ";;@order \g<1> \g<2>;;@way \g<1> \g<3>"
r"^sort: (.+?) (.+?)$", ";;@order \g<1> \g<2>;;@way \g<1> f"
r"^([a-z]*[^s]): (.+?)$", "\g<1>s \g<2>"

Acknowledgements

Based partly on Joseph M. "bisy backson" Reagle's Busy Spunge.

Sean B. Palmer