OVERVIEW
========

Piqi is a set of languages and open-source tools for working with structured
data. It includes:

    - A cross-language data serialization system compatible with Google Protocol
      Buffers. It allows programs implemented in various languages to exchange
      and persist data in a portable manner.

    - Piq -- a human-friendly typed data representation language. It is designed
      to be more convenient for representing, viewing and editing data than
      JSON, XML, CSV, S-expressions and other formats.

    - Piqi -- a powerful data definition language. It is specially designed to be
      used with Piq, but also works as a schema language for other data formats
      including JSON, XML and Protocol Buffers binary format. Tools for
      validating, pretty-printing and converting data between Piq, JSON, XML and
      Protocol Buffers binary format.

    - Piqi-RPC -- an RPC-over-HTTP system for Erlang. It provides a simple way to
      expose Erlang services via JSON, XML and Google Protocol Buffers over
      HTTP.

As a data serialization system, Piqi implements native support for OCaml and
Erlang. Connectivity with other programming languages is provided via Google
Protocol Buffers. Overall, Piqi provides a more natural mapping to functional
programming languages compared to various serialization systems that were
originally designed for imperative or object-oriented languages.

Piqi was inspired by Google Protocol Buffers and specially designed to be
largely compatible with it. Like Protocol Buffers, Piqi relies on type
definitions and supports data schema evolution. The main difference is that Piqi
has a richer data model, high-level modules and a powerful data representation
language (Piq).

The combination of data representation (Piq) and data definition (Piqi)
languages is similar to the concept of "valid XML" (i.e. XML conforming to some
XML Schema). However, unlike XML, Piq has a concise, clean syntax and a data
model similar to those of high-level programming languages.


FURTHER INFORMATION
===================

Full description and documentation can be found at:

       http://piqi.org


INSTALLATION
============

See the INSTALL file for installation instructions.


BUG TRACKER
===========

If you found a bug or have any suggestions, please report them to the issue
tracker:

        http://github.com/alavrik/piqi/issues


CONTRIBUTING
============

Participation and patches are very welcome! The best way to submit a
contribution is to open a pull request on GitHub against "dev" branch.


MAILING LIST
============

For discussions about the usage, development, and future of Piqi, please post on
the Piqi Google Group:

        http://groups.google.com/group/piqi


FILES
=====

  README                this file
  INSTALL               general installation instructions
  INSTALL.erlang        instructions for building Piqi for Erlang
  INSTALL.ocaml         instructions for building Piqi for OCaml
  INSTALL.windows       instructions for building Piqi on Windows
  setenv.sh             installation configuration file
  setenv-mingw.sh       build configuration file for Windows/MinGW
  LICENSE               license
  NOTICE                copyright notice
  AUTHORS               Piqi authors
  CHANGES               release history
  VERSION               current version
  Makefile              main Makefile
  make/                 makefiles and build scripts
  deps/                 third-party components (see NOTICE for details)
  piqi-camlp4/          Piqi syntax extensions for OCaml
  piqicc/               Piqi compiler compiler
  piqic/                Piq interface compiler for OCaml and Erlang
  piqi-tools/           "piqi" command-line utility (piqi tools)
  piqi.org/             Piqi self-specification
  piqilib/              Piqi common library
  piqirun-ocaml/        Piqi runtime library for OCaml
  piqi-erlang/          Piqi runtime library and Piqi tools bindings for Erlang
  piqi-rpc/             Piqi-RPC -- an RPC-over-HTTP system for Erlang
  examples/             examples
  tests/                tests for various piqi functionality; see tests/README
  editors/              text editor plugins for .piq and .piqi files
  src/                  makes rebar happy (rebar is a build tool for Erlang)