----
bdec
----

'bdec', a set of tools for decoding binary files.

.. contents::


Overview
========

Writing decoders for binary formats is typically tedious and error prone.
After reading specification documents, developers have to manually write
code capable of decoding that particular format. This is usually a time
consuming, frustrating, and costly process; it can be the source of many bugs
when the manually written decoders fail to handle edge cases.

Bdec allows developers to write specifications for binary formats using
several simple low-level constructs, which combine in powerful ways to allow
many binary formats to be partially (if not fully) specified. From this
specification, developers can automatically generate source code for C
decoders and encoders.

While there are other high level specification languages (such as ASN.1, or
google protocol buffers), few existing formats make use of these languages,
and such markup languages cannot usually be retro-fitted to existing binary
formats.

Bdec can;

 * Allow specifications to be easily written and maintained.
 * Decode both binary and structured text files.
 * Generate portable, readable, and efficient C decoders and encoders.
 * Run under Windows & Unix operating systems.

The bdec specification uses constructs based loosely on those found in ASN.1.


Getting started
===============

1. Download_ the latest version.
2. Go through the tutorial_.
3. Try writing a specification for your own file formats (referring to the
   documentation_ where necessary).
4. Save lots of time and pain by *not* writing and maintaining hand-written 
   buggy decoders.


Documentation
=============

If you're just getting started, the tutorial_ takes you step by step through
the different concepts used in bdec. Once you're writing your own
specifications, refer to the rest of the documentation_ as required.

For convenience, `pdf documentation`_ is also available.

.. _documentation: docs/
.. _tutorial: docs/tutorial.html
.. _pdf documentation: files/bdec-VERSION.pdf


Support
=======

Any comments or questions can go to the group mailing list at
`bdec-project@yahoogroups.com`_. This is a moderated list, so please be
patient if your question doesn't show up immediately.

.. _bdec-project@yahoogroups.com: mailto:bdec-project@yahoogroups.com


Features
========

* It is easy to write (and read) bdec specifications.
* No need to write a custom decoder (all error conditions are handled 
  internally; decoding either passes or fails).
* The command line application allows visual inspection of problematic files.
* Unicode aware, little-endian / big-endian aware.
* Decode to xml for rapid development (eg: `xml representation of a fat
  bootsector`_).
* Specify fields down to the bit (eg: single bit flags).
* Generated decoders are human readable, easy to use, compile without
  warnings, and have no dependencies.

.. _xml representation of a FAT bootsector: docs/files/fatbootsector.xml


License
=======

The bdec library and all decoders generated by the specification compiler
are available under the `GNU Lesser General Public License (LGPL)`_. In
summary, this means;

 * The decoders can be built and used in any application (including commercial
   closed source applications).
 * If used in a closed source application, the decoder must be dynamically
   linked (eg: .dll in Windows, .so in Linux).
 * The source code (and any modifications) to the decoder must be made
   available to anyone you distribute the decoder to.

.. _GNU Lesser General Public License (LGPL): http://www.gnu.org/licenses/lgpl.txt


Download
========

The easiest way to install bdec is to use python's easy_install_ application.
Run::

  easy_install bdec

to install the latest version of the bdec decoder and compiler.
See the CHANGELOG_ for past releases.

.. _CHANGELOG: changelog.html
.. _easy_install: http://pypi.python.org/pypi/setuptools#installation-instructions


Source
======

The source control tree is available on github at
http://github.com/asdf1011/bdec.

  git clone http://github.com/asdf1011/bdec.git

Dependencies that must be installed are pyparsing_ and mako_.

.. _pyparsing: http://pyparsing.wikispaces.com/
.. _mako: http://www.makotemplates.org/


Similar projects
================

Some other tools that perform 'generic' binary decoding include;

* TSN.1_ - Commercial product with very similar decoding functionality to bdec.
  Can create C, C++, and Java decoders and encoders.
* Encodix_ - Commercial product focussed towards decoders for the
  telecommunications industry.
* Hachoir_ - Tool for inspecting many binary formats.

Projects that generate decoders from high level specifications;

* Asn1c_ Asn.1 compiler; generates C language encoders and decoders.
* `Google protocol buffers`_ - Define file formats in an easy to read text
  specification, and compile them to Java, C++, or Python decoders and encoders.

.. _TSN.1: http://www.protomatics.com/tsn1.html
.. _Hachoir: http://hachoir.org/
.. _Encodix: http://www.dafocus.com/
.. _Asn1c: http://lionet.info/asn1c/
.. _Google protocol buffers: http://code.google.com/apis/protocolbuffers/