postnet.scm: USPS POSTNET Barcode Encoding in Scheme

postnet.scm: USPS POSTNET Barcode Encoding in Scheme
****************************************************

Version 0.2, 2005-07-12, `http://www.neilvandyke.org/postnet-scm/'

by Neil W. Van Dyke <neil@neilvandyke.org>

     Copyright (C) 2004 - 2005 Neil W. Van Dyke.  This program is Free
     Software; you can redistribute it and/or modify it under the terms
     of the GNU Lesser General Public License as published by the Free
     Software Foundation; either version 2.1 of the License, or (at
     your option) any later version.  This program is distributed in
     the hope that it will be useful, but without any warranty; without
     even the implied warranty of merchantability or fitness for a
     particular purpose.  See <http://www.gnu.org/copyleft/lesser.html>
     for details.  For other license options and consulting, contact
     the author.

Introduction
************

This `postnet.scm' Scheme library can be used to generate the United
States Postal Service POSTNET barcode binary pattern, as described in
Chapter 4 of USPS Publication 25, "Designing Letter and Reply Mail,"
(http://pe.usps.gov/text/Pub25/Pub25.htm) dated 2003-06.  This library
supports ZIP, ZIP+4, and DBPC codes.

   The generated binary representation is a Scheme list of boolean
values.  Separate code must be written to render this representation to
a particular printing devices.

Encoding
********

There are several procedures for encoding POSTNET from various input
representations.  It is suspected that most applications will encode
from a string representation, using `string->postnet'.

> (digit-list->postnet digits)
     Yields a POSTNET encoding of a list of digit numbers.  For example:

          (digit-list->postnet '(1 2 3 4 5))
          =>
          (#t #f #f #f #t #t #f #f #t #f #t #f #f #t #t #f
           #f #t #f #f #t #f #t #f #t #f #f #t #f #t #f #t)

> (char-list->postnet chars)
     Yields a POSTNET encoding of a list of characters.  For example:

          (char-list->postnet '(#\1 #\2 #\3 #\4 #\5))
          =>
          (#t #f #f #f #t #t #f #f #t #f #t #f #f #t #t #f
           #f #t #f #f #t #f #t #f #t #f #f #t #f #t #f #t)

> (string->postnet str)
     Yields a POSTNET encoding of a string.  For example:

          (string->postnet "12345-6789 01")
          =>
          (#t #f #f #f #t #t #f #f #t #f #t #f #f #t #t #f
           #f #t #f #f #t #f #t #f #t #f #f #t #t #f #f #t
           #f #f #f #t #t #f #f #t #f #t #f #t #f #f #t #t
           #f #f #f #f #f #f #t #t #f #t #f #f #t #t)

Debugging
*********

Although this package does not render POSTNET for OCR use, for debugging
purposes, the `postnet->debug-string' procedure can be used to
approximate the barcode visually, using ASCII characters.

> (postnet->debug-string postnet)
     Yields a string visual approximation of a POSTNET encoding.  For
     example:

          (postnet->debug-string (string->postnet "12345"))
          => "|...||..|.|..||..|..|.|.|..|.|.|"

Tests
*****

The `postnet.scm' test suite can be enabled by editing the source code
file and loading Testeez (http://www.neilvandyke.org/testeez/).

History
*******

Version 0.2 -- 2005-07-12
     Added Testeez tests.  Minor documentation changes.

Version 0.1 -- 2004-04-14
     Wrote as a diversion over dinner.