view release on metacpan or  search on metacpan

lib/Articulate/Syntax.pm  view on Meta::CPAN

package Articulate::Syntax;
use strict;
use warnings;

use Scalar::Util qw(blessed);
use Module::Load ();

use Exporter::Declare;
default_exports qw(
  instantiate instantiate_array instantiate_selection instantiate_array_selection
  new_response    new_request
  new_credentials new_permission
  new_location    new_location_specification
  dpath_get   dpath_set
  hash_merge
  throw_error
  select_from
  is_single_key_hash
);

use Articulate::Error;
use Data::DPath qw(dpath dpathr);
use Hash::Merge ();

use Articulate::Error;
use Articulate::Credentials;
use Articulate::File;
use Articulate::Item;
use Articulate::Location;
use Articulate::LocationSpecification;
use Articulate::Permission;
use Articulate::Request;
use Articulate::Response;

# sub throw_error { Articulate::Error::throw_error(@_) };
# sub new_location         { Articulate::Location::new_location(@_) };

=head1 NAME

Articulate::Syntax - Common functions and syntactic sugar for
Articulate

=head1 FUNCTIONS

=head3 new_response

See L<Artciulate::Response>.

=head3 new_request

See L<Artciulate::Request>.

=head3 new_credentials

See L<Artciulate::Credentials>.

=head3 new_permission

See L<Artciulate::Permission>.

=head3 new_location

See L<Artciulate::Location>.

=head3 new_location_specification

See L<Artciulate::LocationSpecification>.

=cut

=head3 instantiate_array

C<instantiate_array> accepts an arrayref of values which represent
objects. For each value, if it is not an object, it will attempt to
instantiate one using C<instantiate>.

If you pass C<instantiate_array> a value which is not an arrayref, it
will assume you meant to give it an arrayref with a single item; or, if
you pass it C<undef>, it will return an empty arrayref.

The purpose of this function is to enable the following:

    package Articulate::SomeDelegatingComponent;
    use Moo;
    has delegates_to =>
      is      => 'rw',
      default => sub { [] },
      coerce  => sub{ instantiate_array(@_) };

Which means given config like the following:

    Articulate::SomeDelegatingComponent:
      delegates_to:
        - My::Validation::For::Articles
        - class: My::Validation::For::Images
          args:
            - max_width: 1024
              max_height: 768
        - class: My::Validation::For::Documents
          constructor: preset
          args: pdf

You can be guaranteed that looping through C<< @{ $self->delegates_to }
>> will always produce objects.

=head3 instantiate

Attempts to create an object from the hashref or class name provided.

If the value is a string, it will treat as a class name, and perform
C<< $class->new >>, or, if the method exists, C<< $class->instance >>
will be preferred (for instance, as provided by C<MooX::Singleton>).