README

NAME
    Bubblegum - Opinionated Modern Perl Development Framework

VERSION
    version 0.29

SYNOPSIS
        package Person;

        use Bubblegum::Class;

        has 'firstname' => (
            is       => 'ro',
            required => 1
        );

        has 'lastname' => (
            is       => 'ro',
            required => 0
        );

        sub greet {
            my $self = shift;
            my $subject = shift;

            # fatal assertions
            $self->asa_object;
            $subject->asa_string;

            $subject = $subject->titlecase;

            my $target = $self->firstname->titlecase;
            my $greeting = "Hello %s. My name is %s, nice to meet you.";

            return $subject->format($greeting, $target);
        }

    And elsewhere:

        my $jeff = Person->new(firstname => 'jeffrey');
        say $jeff->greet('amanda');

DESCRIPTION
    Bubblegum is a modern Perl development framework, it enforces common
    best practices and is intended to be used to enhance your Perl
    environment and development experience. The design goal of Bubblegum is
    to be as minimal as possible, enabling as many core features as is
    justifiable, making the common most repetitive programming tasks simply
    a method call away, and having all this available by simply requiring
    this library. This framework is very opinionated and designed around
    convention over configuration. Designed for adoption, all of the
    techniques used in this framework are well-known by experienced Perl
    developers and made conveniently available to programmers at all levels,
    i.e., no experimental features used. Note: This is an early release
    available for testing and feedback and as such is subject to change.

        use Bubblegum;
        # or Bubblegum::Class;
        # or Bubblegum::Role
        # or Bubblegum::Singleton;

    is equivalent to

        use 5.10.0;
        use strict;
        use warnings;
        use autobox;
        use autodie ':all';
        use feature ':5.10';
        use English -no_match_vars;
        use utf8::all;
        use mro 'c3';

    with the exception that Bubblegum implements it's own autoboxing
    architecture. The Bubblegum autobox classes are the foundation for this
    development framework. The decision to re-implement many core and
    autobox functions was based on the desire to build-in data validation
    and design a system using roles for a higher level of abstraction. The
    following functionality is made available simply by using Bubblegum:

        # integers

            my $range = 5->to(1);                   # [ 5, 4, 3, 2, 1 ]

        # floats

            my $strip = 3.1415927->incr->int;       # 4

        # strings

            my $greet = 'hello world'->titlecase;   # "Hello World"

        # arrays

            my $alpha = ['a'..'z'];
            my $map   = $alpha->keyed(1..26);       # { 1=>'a', 2='b', ...}

        # hashes

            my $map = { 1=>'a', 2=>'b', 3=>'c' };
            $map->reset->set(1 => 'z');             # { 1=>'z', 2=undef, 3=>undef }

        # routines

            my $code = ['a'..'z']->iterator;
            my $char = $code->call;                 # a

        # comparison operations

            my $ten = "10";                         # string containing the 10
            $ten->eqtv(10)                          # false, type/value mismatch
            $ten->eq(10)                            # true, coercive comparison
            10->eq($ten)                            # true, same as above
            "10"->type                              # string
            (10)->type                              # integer
            10->typeof('aref')                      # false
            10->typeof('cref')                      # false
            10->typeof('href')                      # false
            10->typeof('int')                       # true
            10->typeof('nil')                       # false
            10->typeof('null')                      # false
            10->typeof('num')                       # true
            10->typeof('str')                       # false
            10->typeof('undef')                     # false

        # include Moo as your default object-system (optional)

            use Bubblegum::Class;                   # Bubblegum w/ Moo
            use Bubblegum::Role;                    # Bubblegum w/ Moo (Role)
            use Bubblegum::Singleton;               # Bubblegum w/ Moo (Singleton)

INTRODUCTION
    Bubblegum makes essential core features and common functionality readily
    available via automation (autoloading, autoboxing, autodying, etc). It
    promotes modern Perl best practices by automatically enabling a standard
    configuration (utf8::all, strict, warnings, features, etc) and by
    extending core functionality with Bubblegum::Wrapper extensions.
    Bubblegum is an opinionated object-oriented development framework, the
    core is designed to leverage as much of the Perl core, 5.10+, as
    possible and uses Moo to provide a minimalistic object system
    (compatible with Moose). This framework is modeled using object-roles
    for a higher-level of abstraction and consistency.

FEATURES
    *   Requires 5.10.0

    *   Enforces Strict Syntax and Enables Warnings

    *   Core Functions Throw Exceptions

    *   Autoboxing With Consistent Functions Names

    *   File and Path Utilities

    *   Date and Time Utilities

    *   Encoding and Decoding Utilities

    *   UTF-8 Encoding For All IO Operations

    *   Modern Method Order Resolution

    *   Modern Minimalistic Object System

    *   Flexible Type Constraint System

    *   Optional Features and Enhancements

RATIONALE
    The TIMTOWTDI (there is more than one way to do it) motto has been a
    gift and a curse. The Perl language (and community) has been centered
    around this concept for quite some time, in that the language "doesn't
    try to tell the programmer how to program" which makes it easy to write
    concise and powerful statements but which also makes it easy to write
    extremely messy and incoherent software (with great power comes great
    responsibility). Another downside is that as the number of decisions a
    programmer has to make increases, their productivity decreases. Enforced
    consistency is a path many other programming languages and frameworks
    have adopted to great effect, so Bubblegum is one approach towards that
    end in Perl.

  Bubblegum Add-Ons
    Additional features and enhancements can be enabled by using the
    Bubblegum::Constraints module which exports type constraint and
    validation functions, and the Bubblegum::Functions module which exports
    various utility functions. Bubblegum is designed as a construction-kit;
    having it's feature-set compartmentalized in such a way as to allow the
    maximum amount of interoperability. Bubblegum can be used along-side any
    of the many object-systems. Hardcore Perl hackers around the world are
    working tirelessly around the clock to give us a better system for
    elegantly defining objects and classes using modern Perl best practices,
    ... but in the meantime, have some Bubblegum.

        use Bubblegum;
        use Bubblegum::Functions 'will';

        # take a moment to reason about the following Perl example.

        my $print = will '@output; say @output';
        $print->curry(1..10)->call; # 12345678910

  Bubblegum Topology
    Bubblegum type classes are built as extensions to the autobox type
    classes. The following is the custom autobox type, subtype and roles
    hierarchy. All native data types inherit their functionality from the
    universal class, then whichever autobox subtype class is appropriate and
    so on. Bubblegum overlays object-roles on top of this design to enforce
    constraints and consistency. The following is the current layout of the
    object roles and relationships. Note, this will likely evolve.

        INSTANCE  -+
            [ROLE] VALUE
                   |
        UNDEF     -+
            [ROLE] ITEM
                   |
        UNIVERSAL -+
            [ROLE] DEFINED
                   |
                   +- SCALAR -+
                   |     [ROLE] VALUE
                   |          |
                   |          +- NUMBER -+
                   |          |     [ROLE] VALUE
                   |          |          |
                   |          |          +- INTEGER
                   |          |          |     [ROLE] VALUE
                   |          |          |
                   |          |          +- FLOAT
                   |          |                [ROLE] VALUE
                   |          |
                   |          +- STRING
                   |                [ROLE] VALUE
                   |
                   +- ARRAY
                   |     [ROLE] REF
                   |     [ROLE] LIST
                   |     [ROLE] INDEXED
                   |
                   +- HASH
                   |     [ROLE] REF
                   |     [ROLE] KEYED
                   |
                   +- CODE
                        [ROLE] VALUE

  Bubblegum Type Operations
    The following classes have methods which can be invoked by variables
    containing data of a type corresponding with the type the class is
    designed to handle.

   Array Operations
    Array operations work on arrays and array references. Please see
    Bubblegum::Object::Array for more information on operations associated
    with array references.

   Code Operations
    Code operations work on code references. Please see
    Bubblegum::Object::Code for more information on operations associated
    with code references.

   Hash Operations
    Hash operations work on hash and hash references. Please see
    Bubblegum::Object::Hash for more information on operations associated
    with hash references.

   Integer Operations
    Integer operations work on integer and number data. Please see
    Bubblegum::Object::Integer for more information on operations associated
    with integers.

   Number Operations
    Number operations work on data that meets the criteria for being a
    number. Please see Bubblegum::Object::Number for more information on
    operations associated with numbers.

   String Operations
    String operations work on data that meets the criteria for being a
    string. Please see Bubblegum::Object::String for more information on
    operations associated with strings.

   Undef Operations
    Undef operations work on variables whose value is undefined. Note, undef
    operations do not work on undef directly. Please see
    Bubblegum::Object::Undef for more information on operations associated
    with undefined variables.

   Universal Operations
    Universal operations work on all data which meets the criteria for being
    defined. Please see Bubblegum::Object::Universal for more information on
    operations associated with array references.

  Bubblegum Wrappers
    A Bubblegum::Wrapper module exists to extend Bubblegum itself and
    further extend the functionality of native data types by letting the
    data bless itself into wrappers (plugins) in a chain-able discoverable
    manner. It's also useful as a technique for coercion and indirect object
    instantiation. The following is an example:

        use Bubblegum;

        my $hash = {1..3,{4,{5,6,7,{8,9,10,11}}}};
        my $json = $hash->json; # load Bubblegum::Wrapper::Json dynamically
        say $json->encode;      # encode the hash as json

        # {"1":2,"3":{"4":{"7":{"8":9,"10":11},"5":6}}}

    The follow list of wrappers are distributed with the Bubblegum
    distribution:

   Digest Wrapper
    The Bubblegum digest wrapper, Bubblegum::Wrapper::Digest, provides
    access to various hashing algorithms to encode/decode messages.

   Dumper Wrapper
    The Bubblegum data-dumper wrapper, Bubblegum::Wrapper::Dumper, provides
    functionality to encode/decode Perl data structures.

   Encoder Wrapper
    The Bubblegum encoding wrapper, Bubblegum::Wrapper::Encoder, provides
    access to content encoding/decoding functionality.

   JSON Wrapper
    The Bubblegum json wrapper, Bubblegum::Wrapper::Json, provides
    functionality to encode/decode Perl data structures as JSON documents.

   YAML Wrapper
    The Bubblegum yaml wrapper, Bubblegum::Wrapper::Yaml, provides
    functionality to encode/decode Perl data structures as YAML documents.

  Extending Bubblegum
    As an alternative to using Bubblegum wrappers, you can rebase (i.e.
    extend) the Bubblegum framework directly, and customize it for your
    application-specific usages. The following is an example of how you can
    accomplish this:

        package MyApp::Core;

        use parent 'Bubblegum';

        use Bubblegum::Namespace Array     => 'MyApp::Core::Object::Array';
        use Bubblegum::Namespace Code      => 'MyApp::Core::Object::Code';
        use Bubblegum::Namespace Float     => 'MyApp::Core::Object::Float';
        use Bubblegum::Namespace Hash      => 'MyApp::Core::Object::Hash';
        use Bubblegum::Namespace Integer   => 'MyApp::Core::Object::Integer';
        use Bubblegum::Namespace Number    => 'MyApp::Core::Object::Number';
        use Bubblegum::Namespace Scalar    => 'MyApp::Core::Object::Scalar';
        use Bubblegum::Namespace String    => 'MyApp::Core::Object::String';
        use Bubblegum::Namespace Undef     => 'MyApp::Core::Object::Undef';
        use Bubblegum::Namespace Universal => 'MyApp::Core::Object::Universal';

        1;

    The example above creates an application-specific package derived from
    Bubblegum and changes the default Bubblegum object class namespaces to
    application-specific ones. Each class will need to be derived from its
    respective Bubblegum counterpart, for example:

        package MyApp::Core::Object::Array;

        use parent 'Bubblegum::Object::Array';

        sub pushpop {
            push @{(shift)}, pop @{(shift)};
        }

        1;

    This allows you to add and/or override object methods and tailor object
    type handling around your specific use-cases.

AUTHOR
    Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Al Newkirk.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.