NAME

Bubblegum::Syntax - Common Helper Functions for Structuring Applications

VERSION

version 0.19

SYNOPSIS

    package Server;

    use Bubblegum::Class;
    use Bubblegum::Syntax -minimal;

    has _hashref, 'config';

    package main;

    use Bubblegum;
    use Bubblegum::Syntax 'file';

    my $config = file('/tmp/config')->slurp->yaml->decode;
    my $server = Server->new(config => $config);

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 @more = $dir->children;

date

The date function returns a DateTime::Tiny instance from an epoch or common date phrase, e.g. yesterday. The first argument should be a date string parsable by Time::ParseDate, it defaults to now.

    my $date = date 'this friday';

date_epoch

The date_epoch function returns an epoch string from a common date phrase, e.g. yesterday. The first argument should be a date string parsable by Time::ParseDate, it defaults to now.

    my $date = date_epoch 'next friday';

date_format

The date_format function returns a formatted date string from an epoch string and a Time::Format template. The first argument should be an epoch date string; the second argument should be a date format string recognized by Time::Format, it defaults to yyyy-mm-ddThh:mm:ss.

    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';

here

The here function returns a Path::Tiny instance for operating on the directory of the file the function is called from.

    my $dir = here;
    my @more = $dir->children;

home

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

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

load

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

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

merge

The merge function uses Hash::Merge::Simple to merge multi hash references into a single hash reference. Please view the Hash::Merge::Simple documentation for example usages.

    my $hash = merge $hash_a, $hash_b, $hash_c;

path

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

    my $dir = path '/';
    my @more = $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';

will

The will function will construct and return a code reference from a string or set of strings belonging to a single unit of execution. This function exists to make creating tiny routines from strings easier. This function is especially useful when used with methods that require code-references as arguments; e.g. callbacks and chained method calls. Note, if the string begins with a semi-colon separated list of variables, e.g. scalar, array or hash, then those variables will automatically be expanded and assigned data from the default array.

    my $print = will '$output; say $output' or raise;
    $print->('hello world');

    # generates a coderef
    will '$output; say $output';

    # is equivalent to
    sub { my $output = shift; say $output; };

    # just as ...
    will '$a;$b; return $b - $a';

    # is equivalent to
    sub { my $a = shift; my $b = shift; return $b - $a; };

    # as well as ...
    will '%a; return keys %a';

    # is equivalent to
    sub { my %a = @_; return keys %a; };

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 {}
    );

-constraints

The constraints export group exports all functions which have the _ prefix and provides functionality similar to importing the "-types" and "-typesof" export groups except that the functions it emits are abbreviated multi-purpose versions of the functions emitted by the -types and -typesof export groups. These functions take a single argument and perform fatal type checking, or, if invoked with no arguments returns a code reference to the fatal type checking routine. The following is a list of functions exported by this group:

• _aref

• _arrayref

• _bool

• _boolean

• _class

• _classname

• _cref

• _coderef

• _def

• _defined

• _fh

• _filehandle

• _glob

• _globref

• _href

• _hashref

• _int

• _integer

• _num

• _number

• _obj

• _object

• _ref

• _reference

• _rref

• _regexpref

• _sref

• _scalarref

• _str

• _string

• _nil

• _null

• _undef

• _undefined

-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 following 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

-minimal

The minimal export group exports all functions from the "-constraints", "-isas", and "-nots" export groups as well as the functionality provided by the "-attr" tag. It is a means to export the simplest type-related functionality.

-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 following 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 following 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

-typing

The typing export group exports all functions from the "-types", "-typesof", "-isas", and "-nots" export groups as well as the functionality provided by the "-attr" tag. It is a means to export all type-related functions minus the multi-purpose functions provided by the "-constraints" export group.

-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 following is a list of functions exported by this group:

• cwd

• date

• date_epoch

• date_format

• dump

• file

• find

• here

• home

• merge

• load

• path

• quote

• raise

• script

• unquote

• user

• user_info

• which

• will

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