NAME

Bubblegum::Syntax - Common Helper Functions for Structuring Applications

VERSION

version 0.11

SYNOPSIS

    package Server;

    use Bubblegum::Class;
    use Bubblegum::Syntax -attr, -typesof;

    has typeof_href, 'config';

    package main;

    use Bubblegum;
    use Bubblegum::Syntax -utils;

    my $data = file('./config')->slurp;
    my $config = $data->yaml->decode if isa_str $data;

    my $server = Server->new(config =>
        $config->lookup('node1.webserver'));

DESCRIPTION

Bubblegum::Syntax is a sugar layer for Bubblegum applications with a focus on minimalism and data integrity.

FUNCTIONS

cwd

The cwd function returns a Path::Tiny instance for operating on the current working directory.

    my $dir = cwd;
    my @subdirs = $dir->children;

date

The date function returns a DateTime::Tiny instance from an epoch or common date phrase, e.g. yesterday.

    my $date = date 'this friday';

date_epoch

The date_epoch function returns an epoch string from a common date phrase, e.g. yesterday.

    my $date = date 'next friday';

date_format

The date_format function returns a formatted date string from an epoch string and a Time::Format template.

    my $date = date_format time;

dump

The dump function returns a representation of a Perl data structure.

    my $class = bless {}, 'main';
    say dump $class;

file

The file function returns a Path::Tiny instance for operating on files.

    my $file  = file './customers.json';
    my $lines = $file->slurp;

find

The find function traverses a directory and returns an arrayref of Path::Tiny objects matching the specified criteria.

    my $texts = find './documents', '*.txt';

home

The home function returns a Path::Tiny instance for operating on the current user's home directory.

    my $dir = home;
    my @subdirs = $dir->children;

load

The load function uses Class::Load to require modules at runtime.

    my $class = load 'Test::Automata';

path

The path function returns a Path::Tiny instance for operating on the directory specified.

    my $dir = path '/';
    my @subdirs = $dir->children;

quote

The quote function escapes double-quoted strings within the string.

    my $string = quote '"Ins\'t it a wonderful day"';

raise

The raise function uses Bubblegum::Exception to throw a catchable exception. The raise function can also store arbitrary data that can be accessed by the trap.

    raise 'business object not saved' => { obj => $business }
        if ! $business->id;

script

The script function returns a Path::Tiny instance for operating on the script being executed.

unquote

The unquote function unescapes double-quoted strings within the string.

    my $string = unquote '\"Ins\'t it a wonderful day\"';

user

The user function returns the current user's username.

    my $nick = user;

user_info

The user_info function returns an array reference of user information. This function is not currently portable and only works on *nix systems.

    my $info = user_info;

which

The which function use File::Which to return a Path::Tiny instance for operating on the located executable program.

    my $mailer = which 'sendmail';

EXPORTS

By default, no functions are exported when using this package, all functionality desired will need to be explicitly requested, and because many functions belong to a particular group of functions there are export tags which can be used to export sets of functions by group name. Any function can also be exported individually. The following are a list of functions and groups currently available:

-attr

The attr export group currently exports a single functions which overrides the has accessor maker in the calling class and implements a more flexible interface specification. If the has function does not exist in the caller's namespace then override will be aborted, otherwise, the has function will now support the following:

    has 'attr1';

is the equivalent of:

    has 'attr1' => (
        is => 'ro',
    );

and if type validators are exported via -typesof:

    use Bubblegum::Syntax -typesof;

    has typeof_obj, 'attr2';

is the equivalent of:

    has 'attr2' => (
        is  => 'ro',
        isa => typeof_obj,
    );

and/or including a default value, for example:

    use Bubblegum::Syntax -typesof;

    has 'attr1' => sub {
        # set default for attr1
    };

    has typeof_obj, 'attr2' => sub {
        # set default for attr2
    };

is the equivalent of:

    has 'attr1' => (
        is      => 'ro',
        lazy    => 1,
        default => sub {}
    );

    has 'attr2' => (
        is      => 'ro',
        isa     => typeof_obj,
        lazy    => 1,
        default => sub {}
    );

-isas

The isas export group exports all functions which have the isa_ prefix. These functions take a single argument and perform non-fatal type checking and return true or false. The follow is a list of functions exported by this group:

• isa_aref

• isa_arrayref

• isa_bool

• isa_boolean

• isa_class

• isa_classname

• isa_cref

• isa_coderef

• isa_def

• isa_defined

• isa_fh

• isa_filehandle

• isa_glob

• isa_globref

• isa_href

• isa_hashref

• isa_int

• isa_integer

• isa_num

• isa_number

• isa_obj

• isa_object

• isa_ref

• isa_reference

• isa_rref

• isa_regexpref

• isa_sref

• isa_scalarref

• isa_str

• isa_string

• isa_nil

• isa_null

• isa_undef

• isa_undefined

-nots

The nots export group exports all functions which have the not_ prefix. These functions take a single argument and perform non-fatal negated type checking and return true or false. The follow is a list of functions exported by this group:

• not_aref

• not_arrayref

• not_bool

• not_boolean

• not_class

• not_classname

• not_cref

• not_coderef

• not_def

• not_defined

• not_fh

• not_filehandle

• not_glob

• not_globref

• not_href

• not_hashref

• not_int

• not_integer

• not_num

• not_number

• not_obj

• not_object

• not_ref

• not_reference

• not_rref

• not_regexpref

• not_sref

• not_scalarref

• not_str

• not_string

• not_nil

• not_null

• not_undef

• not_undefined

-types

The types export group exports all functions which have the type_ prefix. These functions take a single argument/expression and perform fatal type checking operation returning the argument/expression if successful. The follow is a list of functions exported by this group:

• type_aref

• type_arrayref

• type_bool

• type_boolean

• type_class

• type_classname

• type_cref

• type_coderef

• type_def

• type_defined

• type_fh

• type_filehandle

• type_glob

• type_globref

• type_href

• type_hashref

• type_int

• type_integer

• type_num

• type_number

• type_obj

• type_object

• type_ref

• type_reference

• type_rref

• type_regexpref

• type_sref

• type_scalarref

• type_str

• type_string

• type_nil

• type_null

• type_undef

• type_undefined

-typesof

The typesof export group exports all functions which have the typeof_ prefix. These functions take no argument and return a type-validation code-routine to be used with your object-system of choice. The follow is a list of functions exported by this group:

• typeof_aref

• typeof_arrayref

• typeof_bool

• typeof_boolean

• typeof_class

• typeof_classname

• typeof_cref

• typeof_coderef

• typeof_def

• typeof_defined

• typeof_fh

• typeof_filehandle

• typeof_glob

• typeof_globref

• typeof_href

• typeof_hashref

• typeof_int

• typeof_integer

• typeof_num

• typeof_number

• typeof_obj

• typeof_object

• typeof_ref

• typeof_reference

• typeof_rref

• typeof_regexpref

• typeof_sref

• typeof_scalarref

• typeof_str

• typeof_string

• typeof_nil

• typeof_null

• typeof_undef

• typeof_undefined

-utils

The utils export group exports all miscellaneous utility functions, e.g. file, path, date, etc. Many of these functions are wrappers around standard CPAN modules. The follow is a list of functions exported by this group:

• cwd

• date

• date_epoch

• date_format

• dump

• file

• find

• home

• merge

• load

• path

• quote

• raise

• script

• unquote

• user

• user_info

• which

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.

cpanm Bubblegum

perl -MCPAN -e shell
install Bubblegum