----------------------------------------------------------------------



  Blink Tools                                       beta4 2013-02-18
----------------------------------------------------------------------


  License
----------------------------------------------------------------------

  Copyright (c) 2013, Pantor Engineering AB

  All rights reserved.
  
  Redistribution and use in source and binary forms, with or
  without modification, are permitted provided that the 
  following conditions are met:
  
    *  Redistributions of source code must retain the above 
       copyright notice, this list of conditions and the 
       following disclaimer.
      
    *  Redistributions in binary form must reproduce the 
       above copyright notice, this list of conditions and 
       the following disclaimer in the documentation and/or 
       other materials provided with the distribution.
      
    *  Neither the name of Pantor Engineering AB nor the 
       names of its contributors may be used to endorse or 
       promote products derived from this software without 
       specific prior written permission.
  
  THIS SOFTWARE  IS PROVIDED BY  THE  COPYRIGHT  HOLDERS AND
  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  INCLUDING, BUT  NOT  LIMITED TO, THE IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS  FOR A  PARTICULAR PURPOSE ARE
  DISCLAIMED. 

  IN NO EVENT  SHALL THE COPYRIGHT  HOLDERS OR  CONTRIBUTORS
  BE LIABLE FOR ANY  DIRECT,  INDIRECT,  INCIDENTAL, SPECIAL,
  EXEMPLARY, OR  CONSEQUENTIAL  DAMAGES (INCLUDING,  BUT NOT
  LIMITED TO,  PROCUREMENT  OF SUBSTITUTE  GOODS OR SERVICES;
  LOSS OF USE, DATA, OR  PROFITS; OR  BUSINESS  INTERRUPTION)
  HOWEVER CAUSED AND  ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT  LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
  OR OTHERWISE)  ARISING IN  ANY WAY  OUT OF THE USE OF THIS 
  SOFTWARE,  EVEN  IF  ADVISED  OF  THE POSSIBILITY OF  SUCH 
  DAMAGE.


  Overview
----------------------------------------------------------------------

  The Blink tools package provides tools for

    *  dumping compact binary Blink data into annotated hex format or
       pretty-printed text,
   
    *  decoding compact and native binary Blink data into the
       text-based formats Blink Tag, XML and JSON,
   
    *  encoding messages in Blink Tag and XML into native and compact
       binary Blink,

    *  translating between the native and compact binary formats,
     
    *  validating schemas,
   
    *  and translating schemas into Blink schema exchange messages

  Usage
----------------------------------------------------------------------
	
  The tools are accessible through a single command line program named
  blink. The blink progam has seven subcommands dump, dump-native,
  decode, decode-native, encode, encode-native and schema. It also has
  a help command. For details about a specific subcommand you can for
  example type:
  
     > blink help dump

  Some options are common to all subcommands. The most important of
  these is the -S/--schema option which you use for specifying Blink
  schemas to the command.

  The schema for Blink schema exchange is builtin and is active when
  decoding, encoding and dumping messages. You can disable it by
  specifying the -b/--no-builtin option


  Limitations
----------------------------------------------------------------------

  This release has the following limitations:
  
    *  Timestamps are not yet allowed to have timezones specified in
       the Tag and XML formats.
 
    *  JSON is only available as an output format.

    *  Tails of NULL values are not truncated in the encoder. However
       the decoder will accept truncated messages.

    *  Message extensions are not yet natively supported in the Tag, 
       XML and JSON formats (see Message Extensions below)

    *  The decoder will stop at the first strong error it encounters
       rather than skipping the offending message.

    *  In-stream encoding and decoding of schema exchange messages
       is not supported yet.
    

  Examples
----------------------------------------------------------------------

  Encode messages into the Blink compact binary format

    > echo '@Foo|x=1|y=2' | blink encode -S my.blink -o my.cb

  Dump compact binary format into annotated hex format

    > blink dump -S my.blink my.cb

    03                                  // # size: 3
    01                                  // # type: Foo / 1
    01                                  // x: 1
    02                                  // y: 2
 
  Dump compact binary format into pretty-printed text format

    > blink dump -m text -S my.blink my.cb

    Foo ->
      x = 1
      y = 2

  Decode compact binary format into Blink Tag format

    > blink decode -S my.blink my.cb
   
    @Foo|x=1|y=2

  Decode compact binary format into JSON

    > blink decode -S my.blink -m json my.cb 

    [{"$type":"Foo","x":1,"y":2}]

  Translate compact to native binary format

    > blink decode -S my.blink -m native -o my.nb my.cb

  Dump native binary format into annotated hex format

    > blink dump-native -S my.blink my.nb

    14 00 00 00                         // # size: 20
    01 00 00 00 00 00 00 00             // # type: Foo / 1
    00 00 00 00                         // # ext:  none
    01 00 00 00                         // x: 1
    02 00 00 00                         // y: 2

  Translate native to compact binary format

    > blink decode-native -S my.blink -m compact -o my.cb my.nb

  Encode Blink tag into native binary format

    > echo '@Foo|x=1|y=2' | blink encode-native -S my.blink -o my.nb

  Validate a schema

    > blink schema -c my.blink

  Translate a schema into compact binary schema exchange messages

    > blink schema my.blink -o my-schema.cb

  Translate a schema into schema exchange messages in the Tag format
  
    > blink schema -m tag my.blink

    @Blink:GroupDef|Fields=[Optional=N|Name=x|Type={@Blink:U32};Optional=N|\
    Name=y|Type={@Blink:U32}]|Name={Name=Foo}|Id=1
  
  Message Extensions
----------------------------------------------------------------------

  If you want to see what message extensions look like in the compact
  binary format you can annotate a group with an annotation named
  dymo:extension like this:

     @dymo:extension = "Ext" 
     Foo/1 -> 
       u32 x, u32 y
       
  This will effectively add a field 'object [] Ext?' to the internal
  data model.
  
  If you then assume another type

     Bar/2 ->
       string t

  you could do

    > echo '@Foo|x=1|y=2|Ext=[@Bar|t=Voila]' | blink encode -S my.blink | \
      blink -S my.blink dump

  to get

    0c                                  // # size: 12
    01                                  // # type: Foo / 1
    01                                  // x: 1
    02                                  // y: 2
                                        // --- Extension ---
    01                                  // Ext: [1]
                                        //   0 ->
    07                                  //     # size: 7
    02                                  //     # type: Bar / 2
    05 56 6f 69 6c 61                   //     t: "Voila"

  and if you read back the same encoded data with a schema where you don't
  have the extension annotation, you'd only get

    0c                                  // # size: 12
    01                                  // # type: Foo / 1
    01                                  // x: 1
    02                                  // y: 2
                                        // --- Extension ---
    01 07 02 05 56 6f 69 6c 61          // <skipped>
