Al Newkirk > Bubblegum-0.19 > Bubblegum::Syntax

Download:
Bubblegum-0.19.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.19   Source  

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:

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

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

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

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

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

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.

syntax highlighting: