#lang scribble/doc @; THIS FILE IS GENERATED @(require scribble/manual) @(require (for-label (planet neil/ccnum:1:2))) @title[#:version "0.4"]{@bold{ccnum}: Credit Card Number Utilities in Scheme} @author{Neil Van Dyke} License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/ccnum-scheme/" #:underline? #f]{http://www.neilvandyke.org/ccnum-scheme/} @defmodule[(planet neil/ccnum:1:2)] @section{Introduction} This is a Scheme library of a few utilities for validating and formatting credit card numbers. Credit card numbers are represented as strings containing digits and arbitrary whitespace. The procedures are based on information gleaned from dozens of written artifacts of credit card number oral tradition. The author invites free copies of authoritative documentation. Achtung! Do not use this library as anything other than a novelty unless you understand the code thoroughly and can invest in verifying its correctness. Some references that were used: @itemize[ @item{ Jeremy Scott Bradbury, ``@link["http://www.cs.queensu.ca/~bradbury/checkdigit/creditcardcheck.htm"]{Credit Card Check Digit},'' Web page, viewed 2004-05-15. } @item{ Michael Gilleland, ``@link["http://www.merriampark.com/anatomycc.htm"]{Anatomy of Credit Card Numbers},'' Web page, viewed 2004-05-15. } @item{ Happy Hippy, ``@link["http://www.hippy.freeserve.co.uk/credcard.htm"]{Credit Card Magic},'' Web page, viewed 2004-05-15. } ] @section{Validation} The following procedures provide different ways of validating credit card numbers. Most applications will use @tt{credit-card-number-check-digit-ok?} or @tt{credit-card-number-seems-ok?}. @defproc[(check-credit-card-number (str any/c)) any/c]{ Performs a partial validation of the credit card number in @schemevarfont{str}. If the check digit is incorrect, then @tt{#f} is yielded: @SCHEMEBLOCK[ (check-credit-card-number "4408041234567890") ==> #f ] If the check digit is correct, but the issuer cannot be determined, then an integer representing the digit count is yielded: @SCHEMEBLOCK[ (check-credit-card-number "1234567890123452") ==> 16 ] If the check digit is correct and issuer can be determined, then a list of three elements is returned. The first element is a boolean value for whether or not the digit count matches what is known about how many digits the issuer uses for this class of cards. The second element is the digit count. The third element is a symbol loosely identifying the issuer. For example: @SCHEMEBLOCK[ (check-credit-card-number "5551 2121 9") ==> (#f 9 mastercard) (check-credit-card-number "4408041234567893") ==> (#t 16 visa) ] } @defproc[(credit-card-number-check-digit-ok? (str any/c)) any/c]{ Predicate for whether or not the check digit of credit card number @schemevarfont{str} is correct. @SCHEMEBLOCK[ (credit-card-number-check-digit-ok? "4408 0412 3456 7893") ==> #t (credit-card-number-check-digit-ok? "4408 0412 3456 7890") ==> #f (credit-card-number-check-digit-ok? "trump") ==> #f ] } @defproc[(credit-card-number-seems-ok? (str any/c)) any/c]{ Predicate for whether or not the credit card number @schemevarfont{str} ``seems'' to be valid. For a credit card number to ``seem'' valid, the check digit must be correct, the issuer must be identified, and the digit count must match what is known about issuer digit counts. In the following example the check digit is correct, and the issuer (MasterCard) has been identified, but the digit count is too low for a MasterCard number: @SCHEMEBLOCK[ (credit-card-number-check-digit-ok? "5551 2121 9") ==> #t (credit-card-number-seems-ok? "5551 2121 9") ==> #f ] } @section{Formatting} Two procedures are provided for formatting credit card numbers. @defproc[(write-formatted-credit-card-number (str any/c) (port any/c)) any/c]{ Writes credit card number @schemevarfont{str} to output port @schemevarfont{port}, using a format similar to that used on many credit cards. In the current version of this package, the format is always groups of four digits separated by single space characters, although a future version might mimic the format used by the issuer. For example @SCHEMEBLOCK[ (write-formatted-credit-card-number " 1 23 456 7890 12345 6 " (current-output-port)) ] Outputs: @verbatim["1234 5678 9012 3456"] } @defproc[(formatted-credit-card-number (str any/c)) any/c]{ Yields a formatted string representation of credit card number @schemevarfont{str} like that written by @tt{write-formatted-credit-card-number}. @SCHEMEBLOCK[ (formatted-credit-card-number "1234567890123456") ==> "1234 5678 9012 3456" (formatted-credit-card-number " 12 34 56 7890 1234 56") ==> "1234 5678 9012 3456" (formatted-credit-card-number "123 abc") ==> #f ] Note that @tt{(write-formatted-credit-card-number @schemevarfont{n} @schemevarfont{p})} is more efficient than @tt{(display (formatted-credit-card-number @schemevarfont{n}) @schemevarfont{p})}. } @section{History} @itemize[ @item{Version 0.4 --- 2009-03-11 --- PLaneT @tt{(1 2)} Documentation tweaks. } @item{Version 0.3 --- 2009-03-03 --- PLaneT @tt{(1 1)} License is now LGPL 3. Converted to author's new Scheme administration system. Tweaks for PLT 4.x. } @item{Version 0.2 --- 2005-03-29 --- PLaneT @tt{(1 0)} Minus characters (@tt{#\-}) are now accepted as blanks in credit card numbers. } @item{Version 0.1 --- 2004-05-15 First release. } ] @section[#:tag "Legal"]{Legal} Copyright (c) 2004--2009 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 3 of the License (LGPL 3), 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/licenses/ for details. For other licenses and consulting, please contact the author.