[lucy-dev] Tcl API

[Marvin Humphrey <ma...@rectangular.com>]

Greets,

Brad and I were discussing the Tcl API for Lucy on IRC, and I proposed
something like this:

    package require lucy

    set termQuery [lucy termQuery new -field content -term foo]
    set field [$termQuery getField]

The Tcl Style Guide and the example code in the docs for TclOO (in the 8.6b2
release) both influenced that code snippet strongly.

    http://www.tcl.tk/doc/styleGuide.pdf
    http://tcl.tk/man/tcl8.6/TclCmd/class.htm#M13

Regarding naming the package "lucy" (as opposed to "Lucy" or whatever),
section 3.1 of the Style Guide provided germane advice:

    3.1 Package names

    ... It is best to have a simple one word name in all lower-case like http. 

Regarding the capitalization pattern for the command name "termQuery", as in
"lucy termQuery new", and also the use of lowerCamelCase as opposed to
separation_by_underscore:

    5.2 Basic syntax rules

    Exported names for both procedures and variables always start with a
    lower-case letter. 

    ....

    In multi-word names, the first letter of each trailing word is capitalized. Do
    not use under-scores or dashes as separators between the words of a name.

Note that the naming convention for Clownfish methods (which is mandatory and
enforced by the compiler) was deliberately chosen with the task of
automatically deriving both camelCase and lowercase_seperated_by_underscore
names in mind:

    Clownfish:            Get_Field
    Perl, Python, Ruby:   get_field
    Tcl, Java             getField

The use of dashes to prefix parameter names is not spelled out in the official
Tcl Style Guide, but I understand that it's a long-standing convention in Tcl.
I don't know where the it originated, but it is apparently mentioned in Brent
Welch's popular book "Practical Programming in Tcl and Tk", and it is also
used by the Tk library.

The omission of the intermediate name "Search" in "lucy termQuery" is made
possible by the Clownfish requirement that the last component of any class
name within a Clownfish parcel be unique.  I'm not clear on how method
dispatch for objects will work, but for static functions, it seems right for
"lucy" to be published as a Tcl "ensemble" which dispatches to other
ensembles such as "termQuery", "indexer", "queryParser", and so on.

The following passage from the Tcl tutorial was influential in publishing
"lucy" as an ensemble rather than requiring that users spell out fully
qualified procs:

    http://www.tcl.tk/man/tcl8.5/tutorial/Tcl31.html

    As well as providing a nicer syntax for accessing functionality in a
    namespace, ensemble commands also help to clearly distinguish the public
    interface of a package from the private implementation details, as only
    exported commands will be registered as sub-commands and the ensemble will
    enforce this distinction.

Marvin Humphrey