DESCRIPTION
===========

pydsl is a language library written in python. It provides high level functions for Grammars/Alphabets, 
hiding the complexity of parsers and similar tools:
 * guess(input, [gd]): returns a list of _grammar_ and _alphabets_ that are compatible with the input
 * check(d, input): test the input string against the spec
 * extract(gd, input): extract all the slices of the input that are accepted by the definition 

GRAMMARS
--------

supported formats:
 * regular expressions
 * pydsl BNF format
 * mongo database query dictionaries
 * python ply module (only check support)

properties:
 * enum(gd): yields a list of accepted words
 * first(gd): yields a list of the first accepted subword/char
 * minsize(gd): length of the smaller accepted word
 * maxsize(gd): length of the biggest accepted word
 * alphabet(gd): returns the alphabet used by this gd

functions:
 * validate(gd, input): test the input string against the spec. In case of failure, it returns a list of errors

ALPHABETS
---------

Alphabets are a set of grammar definitions that are recognized using a regular grammar. 

properties:
 * grammar_list(ad): return the list of allowed grammars for this alphabet

functions:
 * lexer(ad, input): Generates a tokenlist from a string (it is a special case of translate)


LIBRARY
-------

pydsl also offers functions to store grammars and alphabets into directories and files. Here are the related functions:
 * manager s query: search for an element within a memory
 * manager i identifier: returns information about the element

INSTALLATION
============
 * disttools:
   * python3 setup.py install
 * pip:
   * pip install pydsl

USAGE
=====
To use pydsl as a library for your code, you can:

Loading content from files
--------------------------
    from pydsl.Memory.File.BNF import load_bnf_file
    grammardefinition = loand_bnf_file('myfile.bnf')
    from pydsl.Memory.Loader import *
    mychecker = load_checker(grammardefinition)
    mychecker('mystring') # returns True or False

Loading content from a directory
--------------------------------
First store your grammar definitions in a directory,

    from pydsl.Memory.Storage.Directory import DirStorage
    from pydsl.Guess import Guesser
    a = DirStorage("directory/")
    guess = Guesser([a])
    guess('string')

Using contrib
-------------------
    from pydsl.Memory.Loader import *
    mychecker = load_checker(integer)
    mychecker.check("1234")

BINARIES
========
pydsl also provides a command line interface for the main functions:

 * manager.py : Searchs and displays information about grammar/alphabets
 * check.py: Checks if input data belongs to a grammar
 * guess:py: Returns a list of the types that match the input element
 * validate.py: Perform a validation routine for user data according to a grammar
 * lexer.py: Generates a token list from an input according to an alphaber
 * extract.py: extract all the slices of the input that are accepted by a definition 


REQUIREMENTS
============
 * python >= 2.7
 * optional: ply library ( http://www.dabeaz.com/ply/ )

HELP
====
 * https://github.com/nesaro/pydsl
 * http://pydsl.blogspot.co.uk
 * nesaro@gmail.com

LICENSE
=======
GPLv3, see LICENSE file

ABOUT
=====
pydsl is a language library written in python
Copyright (C) 2008-2013 Nestor Arocha (nesaro@gmail.com)
