--- /dev/null
+asn1ate -- ASN.1 translation library.
+Copyright 2013 Schneider Electric Buildings AB
+
+Introduction
+------------
+
+``asn1ate`` is a Python library for translating ASN.1 into other forms.
+It is intended for code generation from formal ASN.1 definitions, and a
+code generator for ``pyasn1`` is included.
+
+``asn1ate`` is released under a 3-clause BSD license. For details, see
+LICENSE.txt.
+
+
+Caveat
+------
+
+This is very much an alpha-quality prototype. Things that need doing:
+
+* Regression test suite
+* HACK/TODO/BUGs need to be fixed
+* ASN.1 grammar is very incomplete in some places. Known issues:
+
+ - Constraint syntax is currently limited to simple value range constraints (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 53)
+ - Reference syntax is not accepted at all (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 74)
+
+* Improve parser error handling/reporting
+* Allow for semantic analysis, e.g. validity check, warnings for problematic constructs, etc.
+
+
+Usage
+-----
+
+The immediate use of ``asn1ate`` is to generate ``pyasn1`` definitions from
+ASN.1 definitions. The command to do this is::
+
+ $ python .../asn1ate/pyasn1gen.py source.asn1
+
+It will print the ``pyasn1`` equivalent of ``source.asn1`` to stdout.
+
+
+Dependencies
+------------
+
+The only third-party dependency is ``pyparsing``.
+
+Although ``asn1ate`` was initially developed on Python 3.2, it has been tested
+with Python 2.7.3 and should port to older Python versions easily.
+
+
+Design notes
+------------
+
+The ``asn1ate`` package is designed along the same lines as a compiler with a
+driver, a parser, a semantic model and a convention for code generators.
+
+* ``parser.py`` -- a tokenizing parser for ASN.1 per X.680. It currently
+ recognizes a naive sub-set of X.680
+* ``sema.py`` -- a semantic ASN.1 object model, which can be constructed from
+ the AST generated by ``parser.py``
+* ``support/pygen.py`` -- a support library for generating Python code.
+* ``pyasn1gen.py`` -- a code generator to transform a semantic model into
+ ``pyasn1`` syntax. This can be used as a script in which case it will dump
+ output to stdout.
+
+The ASN.1 parser is very ad-hoc, I've experimented with the grammar until I
+found something that accepted our proprietary ASN.1 definition. It's based on
+``pyparsing`` but sets up parse actions to build an annotated AST. Every node of
+interest is annotated with a string denoting its type, e.g. ``Identifier``,
+``TypeAssignment``, etc. I've tried to stay with token types as named in X.680,
+but added custom ones or suppressed others, as necessary to get the AST in a
+useful shape.
+
+Annotated tokens are represented by a simple class containing the type name and
+a list of children (called ``elements``) which may be annotated tokens, lists or
+simple values. This gives a very discoverable tree structure, but there are
+probably cleaner AST representations we could use. Patches welcome.
+
+``asn1ate.sema`` is an object model that represents ASN.1 constructs. It
+describes everything from type assignments to default values and tags, but still
+only the parts of ASN.1 we happen to use here. Most of the logic revolves around
+transforming the AST produced by ``asn1ate.parser`` into a more semantic model
+with proper Python objects.
+
+Codegen is designed to be extensible. In-house we have a set of code generators
+to build an entire protocol stack based on an ASN.1 source, but ``asn1ate`` only
+includes the generally useful one, ``asn1ate.pyasn1gen``.
+
+The most notable members of ``asn1ate.support`` are probably the
+``PythonWriter`` and ``PythonFragment`` classes, which simplify generation of
+correctly indented Python code.
projects / asn2quickder / blobdiff