README.txt

Path: README.txt
Last Update: Tue Apr 03 15:58:59 -0400 2007

Gbarcode

This project is a C extension that wraps the GNU Barcode project using SWIG. The Gbarcode version coincides with the GNU Barcode version, the source of which is distributed along with the gem, as barcode is not usually installed as a dynamically loaded library on most systems. You should not need SWIG to be installed to use this gem, only if you wish to muck around with the SWIG interface file. See README_SWIG.txt for more information.

This library is distributed under the GPL, see LICENSE.txt.

For recent changes, see CHANGELOG.txt

USAGE

The Gbarcode class, being a straight wrap of the GNU Barcode C library, is not very Ruby centric. The example of the usage will illustrate this point.

        require 'rubygems'
        require 'gbarcode'

        # include the module so I type less ;-)
        include Gbarcode

        # There are three stages to creating a barcode
        # 1) allocating the space with a string
        # 2) encoding the string as some barcode
        # 3) printing out the barcode to Postscript

        # allocate the barcode for text "TEST1234"
        bc = barcode_create("TEST1234")

        # encode the barcode using code 39,since code 39 does not use a checksum, we can pass in this additional flag.
        barcode_encode(bc, BARCODE_NO_CHECKSUM | BARCODE_39)

        #print out the barcode to a Postscript file, using the default width and height and page placement
        barcode_print(bc, File.new("testout.ps", "w"), BARCODE_OUT_PS)
				#or
        barcode_print(bc, File.new("testout.eps", "w"), BARCODE_OUT_EPS)

        #print out the barcode to a Postscript EPS file, using the default width and height and page placement
        barcode_print(bc, File.new("testout.eps", "w"), BARCODE_OUT_EPS)

        # you can even read the output to a stream like so
        rd, wr = IO.pipe
        barcode_print(bc, wr,BARCODE_OUT_EPS)
        wr.close() # must close this to use the read pipe
        myEpsBarcodeAsString = rd.readlines().join("\n")
        rd.close()     # it is good practice to also close this pipe

It is good practice to close any IO pipes, or else you may get over-run by zombie processes when using with long-running applications (e.g. Rails)

BARCODE FORMATS

Gbarcode and Rbarcode, being a wrap of GNU Barcode, supports those formats that GNU barcode supports. From the GNU barcode documentation:

The encodings flags are supplied as constants from Gbarcode. Notice the use of the bitwise OR operation on the flag in the USAGE section. Here are a listing of the flags, taken from the GNU barcode docs:

        BARCODE_EAN
        BARCODE_UPC
        BARCODE_ISBN
        BARCODE_128B
        BARCODE_128C
        BARCODE_128
        BARCODE_128RAW
        BARCODE_39
        BARCODE_I25
        BARCODE_CBR
        BARCODE_MSI
        BARCODE_PLS
        BARCODE_93
             The currently supported encoding types: EAN (13 digits, 8 digits,
             13 + 2 add-on and 13 + 5 add-on), UPC (UPC-A, UPC-E, UPC-A with 2
             or 5 digit add-on), ISBN (with or without the 5-digit add-on),
             CODE128-B (the whole set of printable ASCII characters), CODE128-C
             (two digits encoded by each barcode symbol), CODE128 (all ASCII
             values), a "raw-input" pseudo-code that generates CODE128 output,
             CODE39 (alphanumeric), "interleaved 2 of 5" (numeric), Codabar
             (numeric plus a few symbols), MSI (numeric) and Plessey (hex
             digits).  *Note Supported Encodings::.

        BARCODE_ANY
             This special encoding type (represented by a value of zero, so it
             will be the default) tells the encoding procedure to look for the
             first encoding type that can deal with a textual string.
             Therefore, a 11-digit code will be printed as UPC (as well as
             6-digit, 11+2 and 11+5), a 12-digit (or 7-digit, or 12+2 or 12+5)
             as EAN13, an ISBN code (with or without hyphens, with or without
             add-5) will be encoded in its EAN13 representation, an even number
             of digits is encoded using CODE128C and a generic string is
             encoded using CODE128B. Since code-39 offers a much larger
             representation for the same text string, code128-b is preferred
             over code39 for alphanumeric strings.

        BARCODE_NO_CHECKSUM
             Instructs the engine not to add the checksum character to the
             output. Not all the encoding types can drop the checksum; those
             where the checksum is mandatory (like EAN and UPC) just ignore the
             flag.

Here are some flags that can be given to the barcode_print method:

        `BARCODE_OUT_PS'
        `BARCODE_OUT_EPS'
        `BARCODE_OUT_PCL'
        `BARCODE_OUT_PCL_III'
             The currently supported encoding types: full-page postscript and
             encapsulated postscript; PCL (print command language, for HP
             printers) and PCL-III (same as PCL, but uses a font not available
             on older printers).

        `BARCODE_NO_ASCII'
             Instructs the engine not to print the ascii string on output. By
             default the bar code is accompanied with an ascii version of the
             text it encodes.

        `BARCODE_OUT_NOHEADERS'
             The flag instructs the printing engine not to print the header and
             footer part of the file. This makes sense for the postscript
             engine but might not make sense for other engines; such other
             engines will silently ignore the flag just like the PCL back-end
             does

Multiple flags are given by bitwise OR-ing them together (e.g. "BARCODE_NO_CHECKSUM | BARCODE_39" ) For more details on GNU barcode itself, see the GNU Barcode site at www.gnu.org/software/barcode/barcode.html .

FUNCTION REFERENCE

Since RDoc for some reason was not picking up my comments from the C code, here is a reference for the functions exported by the library:

Gbarcode::BarcodeItem = Gbarcode.barcode_create( text )

        Class method for creating a BarcodeItem for the given string
                [text] The barcode text to encode
                +returns+ Gbarcode::BarcodeItem

int = Gbarcode.barcode_delete( Gbarcode::BarcodeItem )

        Class method for destroying the BarcodeItem. Return 0 if successful

int = Gbarcode.barcode_encode( Gbarcode::BarcodeItem, <ENCODING FLAGS> )

        Encodes the BarcodeItem to one of the flags above. Returns 0 if successful.

int = Gbarcode.barcode_print( Gbarcode::BarcodeItem, File, <OUTPUT FLAGS>)’

             Print the bar code described by bc to the specified file.  Valid
             flags are the output type, BARCODE_NO_ASCII and
             BARCODE_OUT_NOHEADERS, other flags are ignored. If any of these
             flags is zero, it will be inherited from bc->flags which therefore
             takes precedence. The function returns 0 on success and -1 in case
             of error (with bc->error set accordingly). In case of success, the
             bar code is printed to the specified file, which won't be closed
             after use.

int = Gbarcode.barcode_position( Gbarcode::BarcodeItem, int width, int height, int xoff, int yoff, double scalef);’

             The function is a shortcut to assign values to the BarcodeItem object. Sets the dimensions, page offsets and scaling factors all in one go. See below for more complete documentation of BarcodeItem.

int = Gbarcode.barcode_encode_and_print(char *text, FILE *f, int wid, int hei, int xoff, int yoff, int flags);’

             The function deals with the whole life of the barcode object by
             calling the other functions; it uses all the specified flags.

Gbarcode::BarcodeItem.ascii

    Returns the ASCII text that is being encoded

Gbarcode::BarcodeItem.ascii=

        Sets the ASCII text to be encoded. Please note that if the barcode was already encoded, you will
        need to re-encode it once this method has been called, or else you will be printing out the wrong barcode!

Gbarcode::BarcodeItem.encoding

        Gets the encoding scheme as a human readable string

Gbarcode::BarcodeItem.partial

        Gets a representation of the barcode as a sequence of integers representing the width of a span.
        The integers alternate between specifying white space and a black bar, starting with white space.

Gbarcode::BarcodeItem.textinfo

        Gets the Postscript representation of the ASCII text that will be printed to the barcode file.

Gbarcode::BarcodeItem.width= Gbarcode::BarcodeItem.width

        Set/get the width in points, which are 1/72  of an inch, or about 1 pixel on most monitors

Gbarcode::BarcodeItem.width= Gbarcode::BarcodeItem.width

        Set/get the height in points

Gbarcode::BarcodeItem.xoff= Gbarcode::BarcodeItem.xoff

        Set/get the page X coordinate offset

Gbarcode::BarcodeItem.yoff= Gbarcode::BarcodeItem.yoff

        Set/get the page Y coordinate offset

Gbarcode::BarcodeItem.margin= Gbarcode::BarcodeItem.margin

        Set/get the margin around the barcode in points

Gbarcode::BarcodeItem.scalef= Gbarcode::BarcodeItem.scalef

        Set/get the scaling factor of the barcode

[Validate]