barcode 0.90.3
A library for drawing bar codes
July 1999
by Alessandro Rubini, Prosa Srl (prosa@prosa.it
)
The barcode package is mainly a C library for creating bar-code
output files. It also includes a command line front-end and (in a
foreseeable future) a graphic frontend.
The package is designed as a library because we think the main use for
barcode-generation tools is inside more featured applications. The
library addresses bar code printing as two distinct problems: creation
of bar information and actual conversion to an output format. To this
aim we use an intermediate representation for bar codes, which is
currently documented in the `ps.c' source file (not in this
document).
Note that the library and the accompanying material is released
according to the GPL license, not the LGPL one. A copy of the GPL is
included in the distribution tarball.
Every barcode-related function acts on a data structure defined in the
`barcode.h' header, which must be included by any C source file
that uses the library. The header is installed by make install.
The definition of the data structure is included here for reference:
struct Barcode_Item {
int flags; /* type of encoding and decoding */
char *ascii; /* malloced */
char *partial; /* malloced too */
char *textinfo; /* information about text positioning */
char *encoding; /* code name, filled by encoding engine */
int width, height; /* output units */
int xoff, yoff; /* output units */
int margin; /* output units */
double scalef; /* requested scaling for barcode */
int error; /* an errno-like value, in case of failure */
};
The exact meaning of each field and the various flags implemented are
described in the following sections.
Even though you won't usually need to act on the contents of this
structure, some of the functions in the library receive arguments that
are directly related to one or more of these fields.
int flags;
-
The flags are, as you may suspect, meant to specify the exact
behaviour of the library. They are often passed as an argument
to barcode functions and are discussed in the next section.
char *ascii;
-
char *partial;
-
char *textinfo;
-
char *encoding;
-
These fields are internally managed by the library, and you are
not expected to touch them if you use the provided API. All
of them are allocated with malloc.
int width;
-
int height;
-
They specify the width and height of the active barcode
region (i.e., excluding the white margin), in the units used
to create output data (for postscript they are points, 1/72th
of an inch, 0.0352 mm). The fields can be either assigned to
in the structure or via Barcode_Position(), at your
choice. If either value or both are left to their default
value of zero, the output engine will assign default values
according to the specified scaling factor. If the specified
width is bigger than needed (according to the scaling factor),
the output barcode will be centered in its requested
region. If either the width of the height are too small for
the specified scale factor, the output bar code will expand
symmetrically around the requested region.
int xoff;
-
int yoff;
-
The fields specify offset from the coordinate origin of the
output engine (for postscript, position 0,0 is the lower left
corner of the page). The fields can be either assigned to in
the structure or via Barcode_Position(), at your choice.
The offset specifies where the white margin begins, not where
the first bar will be printed. To print real ink to the
specified position you should set margin to 0.
int margin;
-
The white margin that will be left around the printed area of
the bar code. The same margin is applied to all sides of the
printed area. The default value for the margin is defined in
`barcode.h' as BARCODE_DEFAULT_MARGIN (10).
double scalef;
-
The enlarge or shrink value for the bar code over its default
dimension. The width and scalef fields interact deeply
in the creation of the output, and a complete description of
the issues appears later in this section.
int error;
-
The field is used when a barcode function fails to host
an errno-like integer value.
A width unit is the width of the thinnest bar and/or space in the
chosen code; it defaults to 1 point if the output is postscript or
encapsulated postscript.
Either or both the code width and the scale factor can be left
unspecified (i.e., zero). The library deals with defaults in the
following way:
- Both unspecified
-
If both the width and the scale factor are unspecified, the
scale factor will default to 1.0 and the width is calculated
according to the actual width of the bar code being printed.
- Width unspecified
-
If the width is not specified, it is calculated according to
the values of scalef.
- Scale factor unspecified
-
If the scale factor is not specified, it will be chosen so
that the generated bar code exactly fits the specified width.
- Both specified
-
The code will be printed inside the specified region according
to the specified scale factor. It will be aligned to the left.
If, however, the chosen width is too small for the specific
bar code and scaling factor, then the code will extend
symmetrically to the left and to the right of the chosen
region.
The following flags are supported by version 0.90.3 of the
library:
BARCODE_ENCODING_MASK
-
The mask is used to extract the encoding-type identifier from
the flags field.
BARCODE_EAN
-
BARCODE_UPC
-
BARCODE_ISBN
-
BARCODE_39
-
The currently supported encoding types: EAN (13 digits, 8
digits, 13 + 2 addon and 13 + 5 addon), UPC (UPC-A, UPC-E,
UPC-A with 2 or 5 digit addon), ISBN (with or without the
5-digit addon) and CODE39. See section 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 enconding 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 ot without hiphens,
with or without add-5) will be encoded in its EAN13
representation and a text-and-digits string will be encoded
using code-39.
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_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.
BARCODE_OUTPUT_MASK
-
The mask is used to extract the output-type identifier from
the flags field.
BARCODE_OUT_PS
-
BARCODE_OUT_EPS
-
The currently supported encoding types: full-page postscript
and encapsulated postscript.
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.
The functions included in the barcode library are declared in the
header file barcode.h. They perform the following tasks:
struct Barcode_Item *Barcode_Create(char *text);
-
The function creates a new barcode object to deal with a
specified text string. It returns NULL in case of failure and
a pointer to a barcode data structure in case of success.
int Barcode_Delete(struct Barcode_Item *bc);
-
Destroy a barcode object. Always returns 0 (success)
int Barcode_Encode(struct Barcode_Item *bc, int flags);
-
Encode the text included in the bc object. Valid flags are
the encoding type (other flags are ignored) and
BARCODE_NO_CHECKSUM (other flags are silently ignored); if the
flag argument is zero, bc->flags will apply. The function
returns 0 on success and -1 in case of error. After
successfull termination the data structure will host the
description of the bar code and its textual representation,
after a failure the error field will include the reason of
the failure.
int Barcode_Print(struct Barcode_Item *bc, FILE *f, int 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 Barcode_Position(struct Barcode_Item *bc, int wid, int hei, int xoff, int yoff, double scalef);
-
The function is a shortcut to assign values to the data
structure.
int Barcode_Encode_and_Print(char *text, FILE *f, int wid, int hei, int xoff, int yoff, double scalef, int flags);
-
The function deals with the whole life of the barcode
object by calling the other functions; it uses all the spefified
flags.
int Barcode_Version(char *versionname);
-
Returns the current version as an integer number of the form
major * 10000 + minor * 100 + release. Therefore, version
1.03.5 will be returned as 10305 and version 0.53 as 5300. If
the argument is non-null, it will be used to return the version
number as a string. Note that the same information is available from
two preprocessor macros: BARCODE_VERSION (the string) and
BARCODE_VERSION_INT (the integer number).
The barcode program is a front-end to access some features of the
library from the command line. It is able to read user supplied
strings from the commandline or a data file (standard input by default)
and encode all of them.
barcode accepts the following options:
-h
-
--help
-
Print a usage summary and exit.
-i filename
-
Specifies a file where strings to be encoded are read from. If
missing (and if -b is not used) it defaults to standard
input. Each data line of the input file will be used to create
one barcode output.
-o filename
-
Output file. It defaults to standard output.
-b string
-
Specifies a single "barcode" string to be encoded.
The option can be used multiple times in order to encode
multiple strings (this will result in multi-page postscript
output or a table of barcodes if -t is specified). The
strings must match the encoding chosen with -e and no
error is printed if they don't match (this may be construed as
a bug).
-e encoding
-
enconding is the name of the chosen encoding format being
used. It defaults to the value of the environment variable
BARCODE_ENCODING or to autodetection if the environment is
also unset.
-g geometry
-
The geometry argument is of the form
"widthxheight+xmargin+ymargin" (the
margin values are optional). The specified values must be
integer numbers and they reperesent print points (I plan to
add support for different units, like inches and millimeters,
but this is currently not supported). The argument is used to
place the printoutcode on the page. Note that an additional
white margin of 10 points is added to the printout. If the
option is unspecified, BARCODE_GEOMETRY is looked up in the
environment, if missing a default size and no margin (but the
default 10 points) are used.
-t table-geometry
-
Used to print several barcodes to a single page, this option
is meant to be used to print stickers. The argument is of the
form "columnsxlines+xmargin+ymargin". The two
margin values are applied symmetrically to the page and the
page is currently assumed to be A4 format (this is a bug,
and I plan to fix it). If the option is not specified,
BARCODE_TABLE is looked up in the environment, otherwise
no table is printed.
-m margin(s)
-
Specify an internal margin for each sticker in the table. The
argument is of the form "xmargin,ymargin" and the margin
is applied symmetrically to the sticker. If unspecified, the
environment variable BARCODE_MARGIN is used or a default
internal margin of 10 points is used.
-n
-
"Numeric" output: don't print the ASCII form of the code,
only the bars.
-c
-
No checksum character (for encodings that allow it, like code 39,
other codes, like UPC or EAN, ignore this option).
-E
-
Encapsulated postscript (default is normal postscript. When
the output is generated a EPS only one text string is encoded.
-p pagesize
-
Spacify a non-default page size. The page size can be specified
in millimeters, inches or points (for example: "210x297mm",
"8.5x11in", "595x842"). If libpaper is available,
you can also specify the page size with its name, like "A3"
or "letter" (libpaper is a standard component of Debian
GNU/Linux, but may be missing elsewhere). The default page
size is your system-wide default if libpaper is there, A4 otherwise.
The program encodes text strings passed either on the command line
(with -b) or retrieved from standard input. The text representation is
interpresed according to the following rules. When auto-detection
of the encoding is enabled (i.e, no explicit encoding type is specified),
the encoding types are scanned to find one that can digest the text string.
- UPC
-
The UPC frontend accepts only strings made up of digits (and,
if a supplemental encodation is used, a blank to separate it).
It accepts strings of 11 digits (UPC-A) or 6 digits (UPC-E).
The 12th digit of UPC-A is the checksum and is added by the
library, if you pass a 12-digit string it will be rejected as
invalid. For UPC-A, a trailing string of 2 digits or 5 digits
is accepted as well. Thefore, valid strings look like one of
the following: "01234567890" (UPC-A), "012345"
(UPC-E), "01234567890 12" (UPC-A, add-2) and
"01234567890 12345" (UPC-A add-5).
- EAN
-
The EAN frontend is similar to UPC; it accepts strings of
digits, 12 or 7 characters long, the checksum digit is added
by the library and a string of 13 or 8 characters is
rejected. The add-2 and add-5 extension are accepted for the
EAN13 encoding. Valid strings look like one of the following:
"123456789012" (EAN-13), "1234567" (EAN-8),
"123456789012 12" (EAN-13 with add-2) and
"123456789012 12345" (EAN-13 with add-5).
- ISBN
-
ISBN numbers are encoded as EAN-13 symbols, with an optional
add-5 trailer. The ISBN frontend of the library accepts real
ISBN numbers and deals with any hyphen and, if present, the
ISBN checksum character before encoding data. Valid
representations for ISBN strings are for example:
"1-56592-292-1", "3-89721-122-X" and "3-89721-122-X
06900".
- code 39
-
The code-39 standard can encode uppercase letters, digits, the
blank space, plus, minus, dot, star, dollar, slash, percent.
Any string that is only composed of such characters is
accepted by the code-39 encoder. To avoid loosing information,
the encoder refuses to encode mixed-case strings (a lowercase
string is nonetheless accepted as a shortcut, but is encoded
as uppercase).
The current management of borders/margins is far from optimal. The
"default" margin applied by the library interferes with the external
rapresentation, but I feel it is mandatory to avoid creating barcode
output with no surrounding white space (the problem is especially
relevant for EPS output).
Code-128 should be supported
This document was generated on 7 July 1999 using the
texi2html
translator version 1.51.