example-lang/README

The "example-lang" directory contains a template for adding a language binding
to Lucy and its object model layer, Clownfish.  See the DevGuide for an
overview of Lucy's layers:

    http://lucy.apache.org/docs/perl/Lucy/Docs/DevGuide.html

To get started, copy "example-lang" to a directory named after the language
you'd like to bind to:

    cp -R example-lang xyz

Most of the C files within the "example-lang/src" directory contain stubs for
routines whose interfaces are defined within "trunk/core".  

    core/src/Lucy/Index/Inverter.cfh        # Declares interface.
    core/src/Lucy/Index/Inverter.c          # all except Invert_Doc()
    example-lang/src/Lucy/Index/Inverter.c  # only Invert_Doc() 

Once all the stubs have been implemented correctly, Lucy will theoretically
build and pass its tests.

There is one pair of files with an interface *not* defined in core.

    example-lang/src/CFBind.h
    example-lang/src/CFBind.c

The CFBind files are there to hold conversion routines which are specific to a
language binding.  Since it is impractical to impose a generic interface, they
are not defined in core.

You may wish to start by referencing a finished language binding to get a feel
for what should go in the CFBind files.

Some of Lucy's classes really ought to be grouped with Clownfish, as they form
something similar to a free floating "standard library" and are not
search-related.  At some point everything under Lucy::Object will probably
migrate to a new namespace:

    Lucy::Object::Obj       => Clownfish::Obj
    Lucy::Object::CharBuf   => Clownfish::CharBuf
    Lucy::Object::VArray    => Clownfish::VArray
    Lucy::Object::Hash      => Clownfish::Hash
    Lucy::Object::BitVector => Clownfish::BitVector
    ...

Other, search-related classes belong with Lucy itself, but are represented
here because they lack one or more implementing functions:

    Lucy::Document::Doc
    Lucy::Analysis::RegexTokenizer
    Lucy::Index::Inverter
    ...