highlights

• recognises user input without imposing any syntax requirements on the end user.
• Corrects finger trouble in a reliable way. (Levenstein edit distance).
• Simple, intuitive, and OPTIONAL definition syntax and compiler tool.
• Multiple equivalent forms of a phrase can be resolved to a single command identifier.
• Refuses to guess if there are multiple interpretations. Instead it provides the remaining candidates and the current match data allowing you to chose based on the specifics of your application domain.
• pure python implementation. (pyrex accelerations planned)
• no complex external dependencies.
• EFFICIENT matching algorithm.

overview

freeform makes it easy to correctly interpret loosely structured user text input without imposing any syntax requirements on the end user. This is particularly usefull for providing text based interfaces over mediums like SMS or instant messaging. Where ambiguity can't be completely resolved it provides you with as much help as possible to make the guess correctly in your application. Typical use: Compile your phrase forms, associating them with a collective command name; prepare the resulting formtable; Then use this table to match user entered phrases to your commands. You can then access the input fields you are interested in using the field names you supplied in your phrase description. Matching considers the whole phrase for ambiguity resolution. It uses levenshteins edit distance metric for individual words to correct for finger trouble. Backtracking is used to handle cases where the content of user fields collides with the recognizable features of your phrase forms. See tool.py for example usage & a tool to assist developing your form descriptions.

examples

The following illustrates simple use.

Given a text file, example-1.forms, containing:

use_objects_with_set: 
    use {object(s)} on {set(list book,safe,fire,door. menu abcd)},
    {object(s)} on {set(list book,safe,fire,door. menu abcd)}, 
    {set(list book,safe,fire,door. menu abcd)} try {object(s)};
    
put_objects_to: 
    put {object(s)} on {location(list shelf,box,floor. menu abc)}, 
    {object(s)} on {location(list shelf,box,floor. menu ijk)};

The following output is from python freeform/tool.py -I data/example-1.forms:

Enter input corresponding to any of the following forms:
use_objects_with_set: KE.use=use WW.object=? KE.on=on LM.set=?
use_objects_with_set: WW.object=? KE.on=on LM.set=?
use_objects_with_set: LM.set=? KE.try=try WW.object=?
put_objects_to: KE.put=put WW.object=? KE.on=on LM.location=?
put_objects_to: WW.object=? KE.on=on LM.location=?

compiled from sources:
use_objects_with_set:
    use {object(s)} on {set(list book,safe,fire,door. menu abcd)},
    {object(s)} on {set(list book,safe,fire,door. menu abcd)},
    {set(list book,safe,fire,door. menu abcd)} try {object(s)};

put_objects_to:
    put {object(s)} on {location(list shelf,box,floor. menu abc)},
    {object(s)} on {location(list shelf,box,floor. menu ijk)};


freeform:apple pear on book
use_objects_with_set: WW.object=[['apple', 'pear']] KE.on=on LM.set=['book']
freeform:use apple pear on book
use_objects_with_set: KE.use=use WW.object=[['apple', 'pear']] KE.on=on LM.set=['book']
freeform:book try apple pear
use_objects_with_set: LM.set=['book'] KE.try=try WW.object=[['apple', 'pear']]
freeform:apple pear on shelf
put_objects_to: WW.object=[['apple', 'pear']] KE.on=on LM.location=['shelf']
freeform:apple pear on shelf
put_objects_to: WW.object=[['apple', 'pear']] KE.on=on LM.location=['shelf']
freeform:apple pear on on shelf
put_objects_to: WW.object=[['apple', 'pear', 'on']] KE.on=on LM.location=['shelf']
freeform:apple pear on a
use_objects_with_set: WW.object=[['apple', 'pear']] KE.on=on LM.set=['a']
freeform:apple pear on i
put_objects_to: WW.object=[['apple', 'pear']] KE.on=on LM.location=['i']
freeform:apple pear on shelf
put_objects_to: WW.object=[['apple', 'pear']] KE.on=on LM.location=['shelf']
freeform: 

warts

• using setuptools, which will be excelent once its finished (imv)

This is alpha software, so is setuptools, which is used to extend pythons distutils behaviour. If setuptools gives you a problem feel free to ignore the setup.py file and run things in place.

freeformc

A simple command line tool, with an optional interactive shell, for developing and testing phrase sources. Instalation is optional this tool can be run in place:

tar -zxvf freeform-$VER.tar.gz; cd freeform-$VER; python freeform/tool.py --help

If you are user of setuptools you can do this:

tar -zxvf freeform-$VER.tar.gz; cd freeform-$VER; python setup.py develop; freeformc --help

freeform.match

The main entry point for the matching engine.

The matching algorithm is implemented by the match sub package. Its main entry points are freeform.match_sentence and freeform.match_command.

freeform.formtable

Implements the compiler tool for constructing the data used by the matching algorithm. The compiler is implemented by the functions: compile, compile_source, yield_forms, yield_fields. These can be found in freeform.formtable.

The compiler takes your form descriptions, collects them according to the command name, that you provide for them, and produces output that should be handed to create_formtable. Before performing matches you need to prepare your formtable by calling formtable_prepare.

If you pass in a dictionary and list instance to either compile or compile_source then you can accumulate the results from successive files into the same formtable. Your form descriptions are collected under the command name you give them. Multiple declarations sharing the same command name are accumulated under the same command.

Strictly speaking you don't need this compiler if you are willing to put together the input for formtable.create_formtable by hand (or using your own tools).

command => commandname: [ keyword | {paramword}] , [keyword|{paramword}* ;
{paramword} => [
        {id} | 
        {id(s)} |
        {id(list one,two,three.)} | 
        {id(menu abc)} |
        {id(list one,two,three. menu abc)}]

freeform_tests

The test suite, test_match.py, and test_freeform.py may be run inplace. At present they provide for reasonably comprehensive coverage of the features offered by the matching algorithm and the guts of the compiler tool.

profile_match.py is where the shared bits of profiling & debug code live.