Badger::Intro - Introduction to the Badger Toolkit
# 1) have more fun # 2) get the job done quicker # 3) make your code skimpier # 4) finish work early # 5) go skateboarding # 6) enjoy life
The Badger toolkit is a collection of Perl modules designed to simplify the process of building object-oriented Perl applications. It provides a set of foundation classes upon which you can quickly build robust and reliable systems that are simple, skimpy and scalable.
Badger was hewn from the living rock of the Template Toolkit. It represents all the generic bits of TT that aren't directly related to template processing. They're also the same kind of generic modules that have appeared in pretty much every non-trivial Perl application I've written over the past 10 years or so. So Badger is essentially a restrospective generalisation of what I've learnt over that time about the right way (or more accurately, some of the less wrong ways) to build Perl applications.
Badger is designed to be lightweight, fast, and as simple as it can be without being too simple. It offers convenience, convention and consistency in an attempt to improve the Kwalitee of your code and make it more Skimpy™ (which is my artistic interpretation of what Michael Schwern refers to as skimmable code - that is, code that is easy to read and also easy to skim over).
Badger isn't just another object system. Although it does include functionality to simplify the process of building objects in Perl 5, that is really just a consequence of the larger goal. That is, to provide a self-contained set of OO modules that work together in a harmonious way to implement a basic platform upon which applications like TT can easily be built.
If you want a comprehensive, highly extensible, postmodern object system then Moose should almost certainly be at the top of your list. The parts of Badger that deal with object construction are in some ways similar to the functionality provided by Moose, not to mention various other object toolkits available from CPAN. However, Badger only goes as far as doing what it needs to in terms of object construction in order to get the rest of the job done. That is, providing a set of objects that do useful things.
Furthermore, the choice between Badger, Moose, or something else isn't an either-or decision. There are lots of things that Moose does, that Badger doesn't, and vice-versa. If you need a really powerful object system then Moose is probably the way forward. But that doesn't mean you can't use Badger's file handling tools, codecs, and other useful bits and pieces alongside your Moose classes. Metaphorically speaking, Badger and Moose are best friends and they play nicely together. Anyone for tennis?
Let's take a quick frolic through the feature list forest to get an idea what Badger is all about.
Badger
Badger includes base classes for creating regular objects (Badger::Base), mixin objects (Badger::Mixin), prototypes/singletons (Badger::Prototype), factory classes (Badger::Factory) and central resource hubs (Badger::Hub).
The Badger::Class module employs metaprogramming techniques to simplify the process of defining object classes. It provides methods to automate many of the annoying trivial tasks required to "bootstrap" an object class: specifying base classes, version numbers, exportable symbols, defining constants, loading utility functions from external modules, creating accessor and mutator methods, and so on. There are also methods that simplify the process of accessing class data (e.g. package variables) to save all that mucking about in symbols tables. Some of these methods will also account for inheritance between related classes, making it much easier to share default configuration values between related classed, for example.
A key feature of Badger::Class is that it does this by a process of "hygienic class construction". What this means in practice is that your object classes don't get polluted with methods that are only used to construct the class (e.g. a method that constructs accessor methods).
Badger::Class can itself be subclassed, allowing you to build your own metaprogramming modules tailored to your particular needs.
Base classes and mixin modules provide functionality for both hard errors in the form of exception-based error handling and soft errors for declining requests (e.g. to fetch a resource that doesn't exist) that aren't failures but require special handling. Methods for debugging (see Badger::Debug) and raising general warnings are also provided. Generic hooks are provided for receiving notification of, or implementing custom handling for errors, warnings and declines. Running alongside this is a generic message formatting system that allow you to define all error/warning/debug messages in one place where they can easily be localised (e.g. to a different spoken language) or customised (e.g. to generate HTML format instead of plain text).
Badger implements an object oriented version of the Exporter module in the form of Badger::Exporter. It works correctly with respect to class inheritance (that is, a subclass automatically inherits the exportable symbols from its base classes) and provides a number of additional features to simplify the process of defining exportable symbols and adding custom import hooks.
The Badger::Utils module provides a number of simple utility functions. It also acts as a delegate to various other standard utility modules (Scalar::Util, List::Util, List::MoreUtils, Hash::Util and Digest::MD5). Badger::Constants defines various constants used by the Badger modules and also of general use. Both these modules are designed to be subclassed so that you can create your own collections of utility functions, constants, and so on.
The Badger::Filesystem module and friends provide an object-oriented interface to a filesystem. Files and directories are represented as Badger::Filesystem::File and Badger::Filesystem::Directory objects respectively. As well as being useful for general filesystem manipulation (in this respect, they are very much like the Path::Class modules), the same modules can also be used to represent virtual filesystems via the Badger::Filesystem::Virtual module. This allows you to "mount" a virtual file system under a particular directory (useful when you're dealing with web sites to map page URLs, e.g. /example/page.html, to the source files, e.g. /path/to/example/page.html). You can also create a virtual file system that is a composite of several root directories (if you're familiar with the Template Toolkit then think of the way the INCLUDE_PATH works).
INCLUDE_PATH
Going hand-in-hand with many basic filesystem operations, the codec modules provide a simple object interface for encoding and decoding data to and from any particular format. The underlying functionality is provided by existing Perl modules (e.g. MIME::Base64, Storable, YAML, etc). The codec modules are wrappers that provide a standard interface to these various different modules. It provides both functional and object oriented interfaces, regardless of how the underlying module works. It also provides the relevant hooks that allow codec objects to be composed into pipeline sequences.
Badger is Open Source and "free" in both "free beer" and "free speech" senses of the word. It's 100% pure Perl and has no external dependencies on any modules that aren't part of the Perl core. Badger is the base platform for version 3 of the Template Toolkit (coming RSN) and has portability and ease of installation as primary goals. Non-core Badger add-on modules can make as much use of CPAN as they like (something that is usually to be encouraged) but the Badger core will always be dependency-free to keep it upload-to-your-ISP friendly.
This section goes into a little more detail into the whys and wherefores of how the Badger came to be. You can safely skip onto the next section if you're in a hurry.
The Badger modules originated in the development of version 3 of the Template Toolkit. Badger is all the generic bits that form the basis of TT3, not to mention a few dozen other Perl-based applications (mainly of the web variety) that I've written over the past few years. The code has evolved and stabilised over that time and is finally approaching a fit state suitable for human consumption.
The Badger is a toolkit, not a framework. What's the difference? Good question. For the purpose of this discussion, a framework is something that requires you to structure your code in a particular way so as to fit into the framework. In contrast a toolkit doesn't concern itself too much with how you write your code (other than some basic principles of structured programming). Instead it provides a set of tools that you can add into your applications as you see fit.
You can use all, some or none of the Badger modules in a project and they'll play together nicely (convivial play is a central theme of Badger, as is foraging in the forest for nuts and berries). However, there's no rigid framework that you have to adjust your mindset to, and very litte "buy-in" required to start playing Badger games. Use the bits you want and ignore the rest. Modularity is good. Monolithicity probably isn't even a real word, but it would be a bad one if it was.
Of course nothing is ever black and white (henceforth known as the "even badgers have grey fur" principle). There's a good deal of overlap between the two approaches and benefits to be had from them both. We embrace a bit of frameworky-ness when it makes good sense, but generally try and keep things as toolkit-like as possible.
The Badger is dependency free (mind alterating substances notwithstanding). The basic Badger toolkit requires nothing more than the core modules distributed with modern versions of Perl (5.8+, maybe 5.6 at a pinch). This is important (for me at least) because the Badger will be the basis for TT3 and other forthcoming modules that require minimal dependencies (e.g. for ease of installation on an ISP or other restricted server). That's not because we don't love CPAN. Far from it - we luurrrve CPAN. We've borrowed liberally from CPAN and tried to make as many things inter-play-nicely-able with existing CPAN modules as possible. But ultimately, one of the goals of Badger is to provide a self-contained and self-consistent set of modules that all work the same way, talk the same way, and don't require you to first descend fifteen levels deep into CPAN dependency hell before you can write a line of code.
The Badger module is a front-end to other Badger modules. You can use it to import any of the exportable items from any other Badger module. Simply specify the module name, minus the Badger:: prefix as a load option.
Badger::
For example:
use Badger Filesystem => 'Dir File', Utils => 'numlike textlike', Constants => 'ARRAY HASH', Codecs => [codec => 'base64'];
This is equivalent to:
use Badger; use Badger::Filesystem 'Dir File'; use Badger::Utils 'numlike textlike', use Badger::Constants 'ARRAY HASH', use Badger::Codecs codec => 'base64';
Note that multiple arguments for a module should be defined as a list reference.
use Badger ...etc... Codecs => [codec => 'base64'];
use Badger::Codecs [codec => 'base64'];
Which is also equivalent to:
use Badger::Codecs codec => 'base64';
This is a handy base class from which you can create your own object classes. It's the successor to Class::Base and provides the usual array of methods for construction, error reporting, debugging and other common functionality.
Here's a teaser:
package My::Badger::Module; use base 'Badger::Base'; sub hello { my $self = shift; my $name = $self->{ config }->{ name } || 'World'; return "Hello $name!\n"; } package main; my $obj = My::Badger::Module->new; print $obj->hello; # Hello World! my $obj = My::Badger::Module->new( name => 'Badger' ); print $obj->hello; # Hello Badger!
Another handy base class (itself derived from Badger::Base) which allows you to create prototype objects. To cut a long story short, it means you can call class methods and have them get automagically applied to a default object (the prototype). It's a little like a singleton, but slightly more flexible.
Badger::Example->method; # delegated to prototype object
The benefit is that you don't have to worry about providing support in your methods for both class and object method calls. Simply call the prototype() method and it'll make sure that any class method calls are "upgraded" to object calls.
prototype()
sub example { my $self = shift->prototype; # $self is *always* an object now }
Yet another handy base class, this time for creating mixin objects that can be mixed into other objects, rather like a generous handful of nuts and berries being mixed into an ice cream sundae. Yummy! Is it tea-time yet?
package My::Sundae; use Badger::Class mixin => 'My::Nuts My::Berries';
This is a class metaprogramming module. Yeah, I know, it sounds like rocket science doesn't it? Actually it's pretty simple stuff. You know all those things you have to do when you start writing a new module? Like setting a version number, specifying a base class, defining some constants (or perhaps loading them from a shared constants module), declaring any exportable items, and so on? Well Badger::Class makes all that easy. It provides an object that has methods for manipulating classes, simple as that. Never mind all that nasty mucking about with package variables. Let the Badger do the digging so you can pop off and enjoy a nice game of tennis. Fifteen Love!
package My::Badger::Module; use Badger::Class 'class'; class->version(3.14); class->base('Badger::Base'); class->exports( any => 'foo bar baz' );
These methods can be chained together like this:
class->version(3.14) ->base('Badger::Base') ->exports( any => 'foo bar baz' );
You can also specify class metaprogramming options as import hooks. Like this:
package My::Badger::Module; use Badger::Class version => 3.14, base => 'Badger::Base', accessors => 'foo bar', mutators => 'wiz bang', constant => { message => 'Hello World', }, exports => { any => 'foo wiz', };
We like this. We think it makes code easier to read when you set a whole bunch of class-related items in one place instead of using a dozen different modules, methods and magic variables to achieve the same thing (we do that for you behind the scenes). We like Schwern too. He understands the virtue of skimmable code. He was probably a badger in a former life.
This exports things. Just like the Exporter module, but better (approximately 2.718 times better in badger reckoning) because it understands objects and knows what inheritance means. It provides some nice methods to declare your exportable items so you don't have to go mucking about with package variables (we do that for you behind the scenes, but you're welcome to do it yourself if getting your hands dirty is your thing).
Oh go on then, I'll give you a quick peek.
package My::Badger::Module; use base 'Badger::Exporter'; __PACKAGE__->export_all('foo bar $BAZ'); __PACKAGE__->export_any('$WIZ $BANG'); __PACKAGE__->export_tags({ set1 => 'wam bam', set2 => 'ding dong' });
As well as mandatory (export_all) and optional (export_any) exportable items, and the ability to define tag sets of items, the Badger::Exporter module also makes it easy to define your own export hooks.
__PACKAGE__->export_hooks({ one => sub { ... }, two => sub { ... }, });
The Badger uses export hooks a lot. They make life easy. For example, you can use the exports hook with Badger::Class and then you don't have to worry about Badger::Exporter at all.
exports
package My::Badger::Module; use Badger::Class exports => { all => 'foo bar $BAZ', any => '$WIZ $BANG', tags => { set1 => 'wam bam', set2 => 'ding dong' }, hooks => { one => sub { ... }, two => sub { ... }, }, };
This defines some constants commonly used with the Badger modules. It also provides a base class from which you can derive your own constants modules.
use Badger::Constants 'TRUE FALSE ARRAY'; sub is_this_an_array_ref { my $thingy = shift; return ref $thingy eq ARRAY ? TRUE : FALSE; }
This provides some debugging methods that you can mix into your own modules as and when required. It supports both compile time and run time debugging statements ("compile time" in the sense that we can eliminate debugging statements at compile time so that they don't have any performance impact, "run time" statements aren't eliminated but can be turned on or off by a flag). And hey, we can do colour! woot! Thirty Love!
An exception object used by the Badger's inbuilt error handling system. Try. Throw. Catch. Forty Love!
This is a whole badger sub-system dedicated to manipulating files and directories in real and virtual filesystems. But I'm only going to show you a two-line example in case you get too excited.
use Badger::Filesystem 'File'; print File('hello.txt')->text;
Sorry, you'll have to read the Badger::Filesystem documentation for further information.
Codecs are for encoding and decoding data between all sorts of different formats: Unicode, Base 64, JSON, YAML, Storable, and so on. Codecs are simple wrappers around existing modules that make it trivially easy to transcode data, and even allow you compose multiple codecs into a single codec container.
use Badger::Codecs codec => 'storable+base64'; my $encoded = encode('Hello World'); # now encoded with Storable and Base64 print decode($encoded); # Hello World
Somewhere over the rainbow, way up high, there's a Badger debugging module that relies on some colour definitions. They live here. One day we'll have a yellow brick road with birds, flowers and little munchkins running around singing and dancing. But for now, we'll have to make do with a rainbow with a pot of strong coffee brewing at the end.
It's a test module. Just like all the other test modules, except that this one plays nicely with other Badger modules. And it does colour thanks to the Rainbow someone left lying around in our back garden!
Rather like the kitchen drawer where you put all the things that don't have a place of their own, the Badger::Utils module provides a resting place for all the miscellaneous bits and pieces. It defines some basic utility functions of its own and also acts as a delegate in case you need any of the functions from Scalar::Util, List::Util, List::MoreUtils, Hash::Util or Digest::MD5. It can also act as a base class if and when you need to define your own custom utility collection modules. You are *so* lucky.
Game, set and match: Mr Badger.
Andy Wardley http://wardley.org/
Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Badger, http://badgerpower.com/
To install Badger, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Badger
CPAN shell
perl -MCPAN -e shell install Badger
For more information on module installation, please visit the detailed CPAN module installation guide.