Notes

November 30th, 2003

Overview

PostDate is an interpreter for a simple postfix notation. Objects are pushed onto the operand stack where operators pop them as required and push back any results.

An object can be one of number, string, code, or dictionary.

Strings are enclosed in parentheses

(this is a string)
(this is a (string) with nested parens)

Code is quoted by braces

{1 1 add} exec print

Numbers and declared names and builtins are referred to directly. There are some builtin operators, defined below. New operators can be defined and stored in dictionaries. Operators are referred to by literal names that are searched for in the dictionary stack. Dictionaries can be pushed or popped from this stack.

Along with the operand and dictionary stacks, there is an execution stack and implicit valid-time stack. The execution stack always has an effective valid time which is used to look up objects in any of the dictionaries. As code is pushed onto the stack the valid time associated with that code object is pushed onto the valid-time stack thereby becoming the effective valid time.

Every operand object has a valid-time. For interactive use of the postdate interpreter, the valid-time is usually the current time. But for objects looked up from a dictionary the valid-time is the time the object was entered into the dictionary. The valid-time of an operand can be changed using the date operator.

The date operator takes a string and an object as operands and interprets the string as a date specifiction in the format YYYYMMDD where YYYYMM are optional. Some special symbols are recognized. Dot, ".", is the current time, "^", is the startof the epoch, and "$" is the end.

Examples

Refer to operator definitions below.

Create a new dictionary called t1 in the current directory; define some values in the dictionary; then step through contents of dictionary.

(t1) dict begin
(a) 1 def
(b) 2 def
t1 save
t1 {print print} forall

Open the same dictionary as above and define a function to add a and b. Execute it and print the result.

(t1) dict begin
(c) {a b add} def
t1 save
c print

In the same dictionary define a to a different value and execute c again. What is the result?

(t1) dict begin
(a) 2 def
t1 save
c print

Set the effective valid time of the function to the current time before executing it, therefore taking the most recent definition of a.

(t1) dict begin
(c) load (.) date exec print

Operators

Operand stack	Operator	Result	Description
any	pop	-	pops the top object from the stack
any	print	any	prints the top object on the stack
int int	add	int	add the top two numbers pushing the result onto the operand stack
int int	sub	int	subtract the top two operands
int int	mul	int	multiply the top two operands
int int	div	int	divide the top two operands
dict	begin	-	pushes the dictionary onto the dictionary stack
string	dict	dict	creates a new dict by opening/creating a file named string which name also becomes a literal
-	end	-	pops the top dictionary from the dictionary stack
dict code	forall	dict	for each member of dict push key,value onto operand stack and execute code
any string	date	any	set the valid time for the object using the string to specify the date in the YYYYMMDD format where YYYYMM are optional and default to the current month and year.
code	exec	-	execute the top operand as postdate code
bool code	if	-	execute code if bool is true
-	stop	-	pop the current execution stack
int int	eq	bool	test top two operands for equality
int int	ne	bool	test not equal
int int	ge	bool	test greater than or equal
int int	gt	bool	test greater than
int int	le	bool	test less than or equal
int int	lt	bool	test less than
int int	and	bool	logical and
int int	or	bool	logical or
int	not	bool	negate
dict	save	-	save the contents to disk of the top member of the dictionary stack
string any	def	-	define string as object in current dictionary
string	load	any	load effective value of symbol from current dictionary stack
string dict	get	any	get effective value of symbol from specified dictionary
-	now	int	push current time onto operand stack
string	range	int int	interpret string as date range and push start and end dates onto stack
key1 key2 dict inv flags	look	dict	queries dict for entries that match key1 key2 in inversion inv. See below for flags.

Flags for the look operator

Mnemonic Value Description
xall 17 Exact match of Key and all values on valid time line
xtog 18 Exact match of key and toggle valid time line
xeff 20 Exact match of key and effective value only
pall 33 Prefix match of key and all values on valid time line
ptog 34 Prefix match of key and toggle valid time line
peff 36 Prefix match of key and effective value only
rall 9 Range between key1 and key2 and all values on valid time line
rtog 10 Range between key1 and key2 and toggle valid time line
reff 12 Range between key1 and key2 and effective values for each matching key only

Mnemonic	Value	Description
xall	17	Exact match of Key and all values on valid time line
xtog	18	Exact match of key and toggle valid time line
xeff	20	Exact match of key and effective value only
pall	33	Prefix match of key and all values on valid time line
ptog	34	Prefix match of key and toggle valid time line
peff	36	Prefix match of key and effective value only
rall	9	Range between key1 and key2 and all values on valid time line
rtog	10	Range between key1 and key2 and toggle valid time line
reff	12	Range between key1 and key2 and effective values for each matching key only

TODO

String handling functions including regex, subs, gsub, etc.
Extended precision arithmetic.
Pipes, streams, channels. The best way of building up queries of btrees and calculating results is using pipelines. Either we create them as part of the language or we stick to using standard shell pipelines and create convenience methods for pd to work as a filter.
Error handling and type checking.
A hash table without temporal properties (a dict that is not a tdb Btree).
Coincidence operator

Bugs

Many, many, many. Memory handling is very bad; there are several leaks including

Strings pushed onto execution stack aren't released
Btree's are not freed
No special char quoting yet