README

=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 http://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