NAME
Bubblegum::Syntax - Common Helper Functions for Structuring Applications
VERSION
version 0.17
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.