Barcode::Code128(3pm)

📦
version 2.21 · 5 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

💖 Barcode::Code128 — the manual page, but make it cute 💖

User Contributed Perl Documentation · Barcode::Code128(3pm)

✨ NAME ✨

Barcode::Code128 — bestie, it generates CODE 128 bar codes. That's the whole vibe. 💅

🌸 SYNOPSIS 🌸

okay so the bare minimum to get this going:

use Barcode::Code128;

$code = new Barcode::Code128;

That's it. That's the whole entrance. Main character energy fr. 👑

🎀 REQUIRES 🎀

Here's what you need on deck:

  • Perl 5.004 — the minimum, no negotiations
  • Carp
  • Exporter
  • GD — and this one is optional, so like, it's giving "nice to have" 🫶

🦋 EXPORTS 🦋

So by default? Nothing. Nada. Zero. The module keeps its hands to itself. 🙈

But — plot twist — there's a whole lil family of constants that stand in for the special characters used in the CODE 128 symbology, and you might wanna pull those in. Say you're doing EAN-128 or UCC-128: the string you encode starts with the FNC1 character. So if you wanted to encode the EAN-128 string "00 0 0012345 555555555 8", you'd do this:

use Barcode::Code128 'FNC1';
$code = new Barcode::Code128;
$code->text(FNC1.'00000123455555555558');

To get this module to export one or more of these characters, just name them on the use statement — or, if you're feeling generous, use the special token ':all' to grab every single one. Examples, because examples slay:

use Barcode::Code128 qw(FNC1 FNC2 FNC3 FNC4 Shift);
use Barcode::Code128 qw(:all);

And here's the complete list of exportable characters. Heads up: they're assigned to high-order ASCII characters purely arbitrarily for the purposes of this module — the values used do not reflect any part of the CODE 128 standard. It's giving "we made it up, don't @ us."

⚠️ Warning, bestie, listen up: using the CodeA, CodeB, CodeC, StartA, StartB, StartC, and Stop codes may cause your barcodes to be invalid and get rejected by scanners. 💀 They get inserted automatically as needed by this module, so like… don't do it.
CodeA      0xf4        CodeB      0xf5         CodeC      0xf6
FNC1       0xf7        FNC2       0xf8         FNC3       0xf9
FNC4       0xfa        Shift      0xfb         StartA     0xfc
StartB     0xfd        StartC     0xfe         Stop       0xff

🌈 DESCRIPTION 🌈

Barcode::Code128 generates bar codes using the CODE 128 symbology. Two ways to serve: it can make images in PNG or GIF format using the GD package, or it can hand you a text string representing the barcode so you can render it yourself with some other technology. Options, we love options. 💅

So the intended use of this module is: make a web page with a bar code on it, print it out, and then fax or mail it to someone who's gonna scan the bar code. The application that spurred its creation was an expense report tool — the employee submitting the report prints out the web page and staples the receipts to it, and then the Accounts Payable clerk scans the bar code to indicate the receipts were received. Fr fr, that's the origin story. 📠✨

The default settings for this module produce a large image that can safely be FAXed several times and still scanned easily. If that requirement isn't important to you, you can generate a smaller image using the optional parameters (described below, keep scrolling bestie 🫶).

If you wanna generate images with this module, you also must have the GD module installed — written by Lincoln Stein, available from CPAN. Using the libgd library, GD can generate files in PNG (Portable Network Graphics) or GIF (Graphic Interchange Format) formats.

Okay so history lesson, no cap: starting with version 1.20, and ending with 2.0.28 (released July 21st, 2004), GD and the underlying libgd library could not generate GIF files due to patent issues. But any modern version of libgd (since 2004) can do GIF, because the patent has expired. And most browsers have zero trouble with PNG files anyway. 🧚

In order to ensure you have a sufficiently modern installation of the GD module to do both GIF and PNG formats, we require version 2.18 of GD (which in turn requires libgd 2.0.28) or higher.

If the GD module is not present, you can still use the module — but you won't be able to use its functions for generating images. You can use the barcode() method to get a string of "#" and " " (hash and space) characters, and use your own image-generating routine with that as input. DIY queen. 👑

To use the the GD module, you'll need to install it along with this module. You can grab it from the CPAN (Comprehensive Perl Archive Network) repository of your choice, under the directory "authors/id/LDS". Visit http://www.cpan.org/ for more info about CPAN. And the GD home page is: http://stein.cshl.org/WWW/software/GD/GD.html 🦋

💖 METHODS 💖

✨ new ✨

Usage:

$object = new Barcode::Code128

Creates a new barcode object. That's it, that's the whole job, and honestly? she ate. 🎀

🦋 option 🦋

Sets or retrieves various options. Here's the vibe check on how she behaves:

  • Call her with one parameter and she'll retrieve the value for that parameter.
  • Call her with more than one parameter and she treats the params as name/value pairs and sets those option values accordingly.
  • Call her with no parameters and she hands you back a hash consisting of the values of all the options (a hash ref in scalar context).

When an option has not been set, its default value is returned. No cap. 💅

You can also set or retrieve any of these options by using it as a method name. For example, to set the value of the padding option, you can use either of these:

$barcode->padding(10);
$barcode->option("padding", 10);

The valid options, and the default value and meaning of each, are:

  • width — default undef — Width of the image (*)
  • height — default undef — Height of the image (*)
  • border — default 2 — Size of the black border around the barcode
  • scale — default 2 — How many pixels for the smallest barcode stripe
  • font — default "large" — Font (**) for the text at the bottom
  • show_text — default 1 — True/False: display the text at the bottom?
  • font_margin — default 2 — Pixels above, below, and to left of the text
  • font_align — default "left" — Align the text ("left", "right", or "center")
  • transparent_text — default 1/0 (***) — True/False: use transparent background for text?
  • top_margin — default 0 — No. of pixels above the barcode
  • bottom_margin — default 0 — No. of pixels below the barcode (& text)
  • left_margin — default 0 — No. of pixels to the left of the barcode
  • right_margin — default 0 — No. of pixels to the right of the barcode
  • padding — default 20 — Size of whitespace before & after barcode
🌟 * Width and height are the default values for the $x and $y arguments to the png, gif, or gd_image method (q.v.)
🌟 ** Font may be one of the following: "giant", "large", "medium", "small", or "tiny". Or, it may be any valid GD font name, such as "gdMediumFont".
🌟 *** The "transparent_text" option is "1" (true) by default for GIF output, but "0" (false) for PNG. This is because PNG transparency is not supported well by many viewing software The background color is grey (#CCCCCC) when not transparent.

🌈 gif 🌈

🌈 png 🌈

🌈 gd_image 🌈

Usage:

$object->png($text)
$object->png($text, $x, $y)
$object->png($text, { options... })

$object->gif($text)
$object->gif($text, $x, $y)
$object->gif($text, { options... })

$object->gd_image($text)
$object->gd_image($text, $x, $y)
$object->gd_image($text, { options... })

These methods generate an image using the GD module. The gd_image() method returns a GD object, which is useful if you want to do additional processing to it using the GD object methods. The other two create actual images.

💀 NOTE: GIF files require an old version of GD, and so you probably are not able to create them — see below.

The gif() and png() methods are wrappers around gd_image() that create the GD object and then run the corresponding GD method to create output that can be displayed or saved to a file. Note that only one of these two methods will work, depending on which version of GD you have — see below. The return value from gif() or png() is a binary file, so if you are working on an operating system (e.g. Microsoft Windows) that makes a distinction between text and binary files be sure to call binmode(FILEHANDLE) before writing the image to it, or the file may get corrupted. Example:

open(PNG, ">code128.png") or die "Can't write code128.png: $!\n";
binmode(PNG);
print PNG $object->png("CODE 128");
close(PNG);

If you have GD version 1.20 or newer, the PNG file format is the only allowed option. Conversely if you have GD version prior to 1.20, then the GIF format is the only option. Check the $object->image_format() method to find out which you have (q.v.). 👑

Note: All of the arguments to this function are optional. If you have previously specified $text to the "barcode()", "encode()", or "text()" methods, you do not need to specify it again. The $x and $y variables specify the size of the barcode within the image in pixels. If size(s) are not specified, they will be set to the minimum size, which is the length of the barcode plus 40 pixels horizontally, and 15% of the length of the barcode vertically. See also the $object->width() and $object->height() methods for another way of specifying this.

If instead of specifying $x and $y, you pass a reference to a hash of name/value pairs, these will be used as the options, overriding anything set using the $object->option() (or width/height) method (q.v.). However, this will not set the options so any future barcodes using the same object will revert to the option list of the object. If you want to set the options permanently use the option, width, and/or height methods instead. 🙈

🎀 barcode 🎀

Usage:

$object->barcode($text)

Computes the bar code for the specified text. The result will be a string of '#' and space characters representing the dark and light bands of the bar code. You can use this if you have an alternate printing system besides using GD to create the images. So handy, so iconic. ✨

Note: The $text parameter is optional. If you have previously specified $text to the "encode()" or "text()" methods, you do not need to specify it again.

🧚 Housekeeping Functions 🧚

The rest of the methods defined here are only for internal use, or if you really know what you are doing. Some of them may be useful to authors of classes that inherit from this one, or may be overridden by subclasses. If you just want to use this module to generate bar codes, you can stop reading here. No shade, bestie, go live your life. 💜

⭐ encode ⭐

Usage:

$object->encode
$object->encode($text)
$object->encode($text, $preferred_code)

Do the encoding. If $text is supplied, will automatically call the text() method to set that as the text value first. If $preferred_code is supplied, will try that code first. Otherwise, the codes will be tried in the following manner:

  1. If it is possible to use Code C for any of the text, use that for as much of it as possible.
  2. Check how many characters would be converted using codes A or B, and use that code to convert them. If the amount is equal, code A is used.
  3. Repeat steps 1 and 2 until the text string has been completely encoded.

🦋 text 🦋

Usage:

$object->text($text)
$text = $object->text

Set or retrieve the text for this barcode. This will be called automatically by encode() or barcode() so typically this will not be used directly by the user.

🌸 start 🌸

Usage:

$object->start($code)

If the code (see code()) is already defined, then adds the CodeA, CodeB, or CodeC character as appropriate to the encoded message inside the object. Typically for internal use only.

🎀 stop 🎀

Usage:

$object->stop()

Computes the check character and appends it along with the Stop character, to the encoded string. Typically for internal use only. Periodt. 💅

💖 code 💖

Usage:

$object->code($code)
$code = $object->code

Set or retrieve the code for this barcode. $code may be 'A', 'B', or 'C'. Typically for internal use only. Not particularly meaningful unless called during the middle of encoding.

🌟 CLASS VARIABLES 🌟

None. That's it. Empty. A void. She simply does not have any. 💀

🚨 Unrecognized option ($opt) for $class

Bestie, that option? Not a thing for this module. 💀 $class is supposed to say Barcode::Code128, but if somebody inherited this module into another one, that other module's name shows up here instead. And $opt is the option you tried to sneak in. It did not slay.

😭 The gd_image() method of Barcode::Code128 requires the GD module

To call gd_image(), png(), or gif(), you need the GD module installed. That's the module that actually makes the picture. No GD? Then the only thing you get to do is barcode(). Periodt.

🔢 Scale must be a positive integer

The scale factor for gd_image(), png(), or gif() has to be a positive integer. That's the whole rule. No vibes-based fractional scaling, bestie.

🖼️ Border ($border) must be a positive integer or zero

The border option can't be a fraction and it can't be negative. Zero is fine, positive whole numbers are fine, everything else is a no. ✋

🔤 Invalid font $font

That font is not valid. Important caveat though — this check is done with GD->can(), so any subroutine in GD.pm will pass the test... but only actual fonts will actually work. 😭 So passing the check does not mean it works. Check the GD module documentation for more on that.

📏 Image width $x is too small for bar code

You gave a width that doesn't leave enough room for the barcode to show up. The minimum allowed is the size of the bar code itself plus 40 pixels. If you're unsure, just don't pass a width at all when you call gd_image(), png(), or gif(), and it'll use the minimum for you. 🫶

📐 Image height $y is too small for bar code

Same situation but vertical — your height doesn't leave enough space for the barcode. The minimum allowed here is 15% of the width of the bar code. In doubt? Omit the height when calling gd_image(), png(), or gif() and it'll default to the minimum. Easy.

💥 Unable to create $x x $y image

Something went wrong initializing a GD::Image object at that size. Maybe $x and $y are just too big for memory? 🤔 That's the suspicion, anyway.

🎀 The GD-module-and-its-version squad

These four are all the same family of problem — the GD module, or the right version of the GD module for that method, wasn't there:

  • The gif() method of Barcode::Code128 requires the GD module
  • The gif() method of Barcode::Code128 requires version less than 1.20 of GD
  • The png() method of Barcode::Code128 requires the GD module
  • The png() method of Barcode::Code128 requires at least version 1.20 of GD

The tea ☕: you need GD version 1.20 or greater to make PNG files, and a version of GD less than 1.20 to make GIF files. Yes, genuinely. Install accordingly.

🙈 No encoded text found

This one comes from barcode(). Usually it means there was no text message supplied — not during the current method call, and not in a previous method call on the same object either. It shows up when you try to make a barcode by calling gd_image(), png(), gif(), or barcode() without ever having specified the text to encode. Give it something to chew on, bestie. 💅

📭 No text defined

This message comes from encode(), and typically means there was no text message supplied during the current method call or in a previous method call on the same object. Same vibe as above, different function.

❌ Invalid preferred code ``$preferred_code''

This means encode() was called with the $preferred_code optional parameter, but it wasn't one of A'', B'', or ``C''. Only those three, no others, not even a little. 🌈

🌀 Sanity Check Overflow

Okay this one is serious. It's an error in encode() indicating a serious problem attempting to encode the requested message — specifically, it means an infinite loop was generated. If you get this, please contact the author. Fr fr. 😭

🔍 Unable to find encoding for ``$text''

Part or all of the message couldn't be encoded. This may mean the message had characters that aren't encodable in the CODE 128 character set — like a character with an ASCII value higher than 127 (except the special control characters defined in this module). Not everything is encodable, and that's just facts.

🔀 Unable to switch from ``$old_code'' to ``$new_code''

Another serious error, this one in start(). It indicates a serious problem happened when switching between the codes (A, B, or C) of CODE 128. If you get this error, please contact the author. 👑

▶️ Unable to start with ``$new_code''

Also serious, also in start(). It means a serious problem occurred when starting encoding in one of the codes (A, B, or C) of CODE 128. If you get this, please contact the author. Same energy as above.

❓ Unknown code ``$new_code'' (should be A, B, or C)

A serious error in code(), meaning an invalid argument got supplied. Only the codes (A, B, or C) of CODE 128 may be supplied here — that's it. If you get this error, please contact the author. 🫡

🐛 BUGS

At least some web browsers just do not seem to handle PNG files with transparent backgrounds correctly. So as a result, the default for PNG is to generate barcodes without transparent backgrounds — the background is grey instead. Iconic workaround behavior, honestly. 💀

👑 AUTHOR

William R. Ward, wrw@bayview.com

👀 SEE ALSO

and that's the whole page, bestie!! 🎀✨ This gorgeous little manual page is from perl v5.36.0, dated 2022-12-11, and it lives at Barcode::Code128(3pm) in the User Contributed Perl Documentation. Go forth and encode responsibly. 💖🦋🌸

📦 where this page comes from