numspell.scm: Spelling Numbers as English in Scheme

numspell.scm: Spelling Numbers as English in Scheme
***************************************************

Version 0.1, 2006-05-07, `http://www.neilvandyke.org/numspell-scm/'

by Neil Van Dyke <neil@neilvandyke.org>

     Copyright (C) 2006 Neil 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
************

The `numspell.scm' library provides the ability to "spell" Scheme
numbers in English.  This is useful for writing numbers on banking
checks and other legal documents, as well as for speech generation.

   Most rational numbers in Scheme are presently supported.  For
example:

     (number->english 123456)
     => "one hundred twenty-three thousand four hundred fifty-six"
     (number->english (/ 4 -6))
     => "negative two over three"
     (number->english (exact->inexact (/ 4 -6)))
     => "negative zero point six six six six six six" ; approx.

   The number names supported by `numspell.scm' are taken from a version
of the Wikipedia "Names of large numbers"
(http://en.wikipedia.org/wiki/Names_of_large_numbers) article.  Both
short and long scales
(http://en.wikipedia.org/wiki/Long_and_short_scales) are supported,
through different procedures, with short scale being the default.  For
example:

     (number->english             (expt 10 15))
     => "one quadrillion"
     (number->short-scale-english (expt 10 15))
     => "one quadrillion"
     (number->long-scale-english  (expt 10 15))
     => "one thousand billion"

   Note: Some numbers, such as very large and very small non-integers
printed by some Scheme implementations in exponential notation, are not
supported by the current version of `numspell.scm'.

   `numspell.scm' requires R5RS, SRFI-6 (string ports), and SRFI-11
(`let-values').

Interface
*********

The public interface consists of a few procedures.

> (write-number-as-english num port)
> (write-number-as-short-scale-english num port)
> (write-number-as-long-scale-english num port)
     Spell number NUM to output port PORT.  If NUM cannot be spelt, an
     error is signaled.

> (number->english num)
> (number->short-scale-english num)
> (number->long-scale-english num)
     Yield a string that spells number NUM.  If NUM cannot be spelt, an
     error is signaled.

Tests
*****

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

History
*******

Version 0.1 -- 2006-05-07
     Initial release