Announce: TOPIC database specification
mss
SYNOPSIS
This document describes the formal specifications of the TOPIC
database format and serves as its canonical reference.
Designed for humans first and machines second, the TOPIC format
attempts to provide a standardized structure for plain text
databases that's easy to read and edit in most text editors, and
easy to programmatically parse as well [i].
Uses include: knowledge-bases, glossaries, apropos, notes...
KEY CONCEPTS
- TOPIC databases are OS neutral.
- TOPIC databases are self-indexing.
- TOPIC databases provide associations linking blocks of data.
- TOPIC databases are written and read as standard ASCII [ii], so
virtually any plain text editor is suitable for editing chores.
- TOPIC databases use fundamentally simple markup [iii] employing
only the tab and comma characters to delimit content.
- TOPIC databases allow the end user to label data in a straight
foreword, intuitive manner.
TAGS
- Tags are always located above the block it describes, alone on a
single line.
- Tags only contain alpha/numeric characters A-Z, a-z, 0-9, and
optionally spaces [HEX:20] [iv].
- A tag can be either a single word, or a group of words.
- Multiple tags are comma delimited [HEX:2C] [iv].
BLOCKS
- A block is always located below the tags that describe it.
- A block may contain any number of lines, each beginning with a
horizontal tab character [HEX:09] [iv].
- Empty lines within a block are valid.
LINES
- Lines are terminated with one of CR [HEX:0D], LF [HEX:0A], or a
CR/LF pair [iv].
- No limits are imposed on the length of a given line [v].
ASSOCIATIONS
Using multiple tags establishes associations between otherwise
unrelated blocks. In the example below, the first block has a tag
named 'Apples', the second block has a tag named 'Oranges', and both
blocks have a common tag named 'Fruit' as shown in the next two
blocks:
Apples, Fruit
Block line 1
Block line 2
Block line n...
Oranges, Fruit
Block line 1
Block line 2
Block line n...
This means you can stream the first block with the 'Apples' tag,
stream the second block with the 'Oranges' tag, or stream both
blocks via the 'Fruit' tag. The advantage gained is that your data
can be filtered in an arbitrary manner. For instance, you could have
twelve blocks, each with differing month tags, and a common year tag
allowing you to scrutinize your data by month as well as year...
PARSING
- TOPIC databases are parsed line-by-line sequentially from top to
bottom, and left to right.
- Parsing ignores blocks, seeking only tags matching the current
query, and when a match is found, outputs the associated block.
- Because a given tag can define multiple blocks, the data should
be parsed in its entirety 'per query'.
MODIFICATIONS
There are no formally sanctioned modifications to the TOPIC database
specification. However, the user is free to extend and alter the
format as best fits the need provided all legalese is observed.
HEX TABLE
ASCII/hexadecimal equivalents used in this document:
0 1 2 3 4 5 6 7 8 9 A B C D E F
0 ^@ ^A ^B ^C ^D ^E ^F ^G ^H ^I ^J ^K ^L ^M ^N ^O
1 ^P ^Q ^R ^S ^T ^U ^V ^W ^X ^Y ^Z ^[ ^\ ^] ^^ ^_
2 SPC ! " # $ % & ' ( ) * + , - . /
3 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4 @ A B C D E F G H I J K L M N O
5 P Q R S T U V W X Y Z [ \ ] ^ _
6 ` a b c d e f g h i j k l m n o
7 p q r s t u v w x y z { | } ~ DEL
UPDATES
Updates, parsing examples, and other resources are located at:
http://www.topcat.hypermart.net/index.html
NOTES
i. Parse: To scan/analyze data looking for a desired pattern.
ii. ASCII: American Standard Code for Information Interchange.
iii. Markup: A system for annotating text.
iv. See topic 'HEX TABLE' for ASCII/hexadecimal equivalents.
v. Caveat: The user should recognize the constraints governing
both the hardware and software rendering the data.
LEGALESE
The TOPIC database specification is copyright Topcat Software LLC.
and is absolutely free for anyone to use for any reason in
perpetuity. A single line citation is requested in the form of:
TOPIC database specification by Topcat Software LLC.
eof