Unification of Commands and Formatters

Syntax

Current syntax:

input    ::= '/' command? format?
           | '/' ( path | role ( '/' path )? )
             ( ( '/' | '/' command format? | '/'? format ) filter? )?
command  ::= identifier '(' cmd_args? ')'
format   ::= '.' identifier ( '(' cmd_args? ')' )?

New syntax:

input          ::= '/' ( lead_statement statement* )?
                 | '/' role ( '/' ( lead_statement statement* )? )?
                 | '/' ( role '/' )? path ( statement+ filter? )?
                 | '/' ( role '/' )? path '/' ( lead_statement statement* )? filter?
lead_statement ::= identifier '(' cmd_args? ')'
statement      ::= '.' identifier ( '(' cmd_args? ')' )?

Examples

Some of the commands and formatters don't really exist or don't work as described. They are given in order to illustrate some specific aspects of the command/formatter interaction.

Commands

• htsql:root() is a command that displays the HTSQL title page.
• htsql:select() performs an SQL request and produces the results. htsql:insert(), htsql:update(), htsql:merge() and htsql:delete() has the same interface as htsql:select().
• htsql:import() accepts a POST request that contains CSV data describing a series of HTSQL requests and performs them. Currently it produces nothing. htsql:interact() is quite similar to htsql:import().
• htsql:meta() generates HTSQL metadata containing the information about the aspects and their fields which the user could operate on. In principle, htsql:meta() could possibly produce a tree output, but here we'll assume that it doesn't.
• htsql:migrate() generates a sequence of HTSQL statements which could reproduce the current state of the database.
• pedigree:draw() displays the family tree of an individual.

Formatters

• .htsql:xml() expects a row generator; produces XML output. .htsql:txt(), .htsql:html() and many other formatters work the same way.
• .htsql:js() expects either a row generator or HTSQL metadata; produces the respective JSON output.
• .htsql:sql() expects a producer command, displays SQL statements which this command would generate and execute.
• .htsql:jpg() expects either HTSQL metadata or Pedigree data, produces the corresponding JPEG image.
• .htsql:dot() expect HTSQL metadata, produces a DOT file for GraphViz, which represent the metadata in the graph form.
• .htsql:gz() packs the output.

Input/Output

• the HTSQL request. Could it be an output? For instance /some_command_producing_an_htsql_request().select(). Why not?
• A row generator. htsql:select() produces it, .htsql:xml() expects it.
• Execution plan. Used by .htsql:sql().
• HTSQL metadata. Generated by htsql:meta().
• WSGI output. Most commands could do it as well. .htsql:gz() expects it.
• Pedigree output. Generated by pedigree:draw(), expected by .htsql:jpg().

Summary

Statement	Input Interfaces	Output Interfaces
The request (the implicit heading statement)	--	request, WSGI
The HTSQL application (the implicit trailing statement)	WSGI	--
htsql:root()	request	WSGI
htsql:select()	request	row generator, SQL plan, WSGI
htsql:import()	request	WSGI
htsql:meta()	request	metadata, WSGI
htsql:migrate()	request	WSGI
pedigree:draw()	request	pedigree
htsql:xml()	request, row generator	WSGI
htsql:js()	request, row generator, metadata	WSGI
htsql:sql()	request, SQL plan	WSGI
htsql:jpg()	metadata, pedigree	WSGI
htsql:dot()	metadata	WSGI
htsql:gz()	request, WSGI	WSGI

Semantics