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

pydsl is a language library written in python

GRAMMARS
--------

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

each grammar definition has the following 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

pydsl offer a set of functions that use _grammar definitions_
 * validate(gd, input): test the input string against the spec. In case of failure, it returns a list of errors

ALPHABETS
---------

alphabet abstraction is also available. 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 that use _alphabets_:
 * lexer(ad, input): Generates a tokenlist from a string (it is a special case of translate)

functions that use both _alphabets_ and _grammar definitions_:
 * 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 

pydsl also offers library 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.Storage.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
========
Memory Management
-----------------
 * manager.py : Searchs and displays information about grammar/alphabets

Grammars
--------
 * 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


CONTRIB
=======

contrib directory contains several types of elements. Those elements are either imported by pydsl or used as a function argument for binaries.

 * grammars
   * dict/filetype.dict: A list of filetypes, which are types
   * dict/regexp.dict: A list of Regular expressions, which are types
 * alphabets

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 formal language framework.
Copyright (C) 2008-2013 Nestor Arocha (nesaro@gmail.com)
