Path::Resolver::Role::Resolver - resolving paths is just what resolvers do!

Path-Resolver documentation Contained in the Path-Resolver distribution.

Index

Code Index:

NAME

Top

Path::Resolver::Role::Resolver - resolving paths is just what resolvers do!

VERSION

Top

version 3.100451

DESCRIPTION

Top

A class that implements this role can be used to resolve paths into entities. They declare the type of entity that they will produce internally, and may have a mechanism for converting that entity into another type before returning it.

METHODS

Top

entity_at

  my $entity = $resolver->entity_at($path);

This is the most important method in a resolver. It is handed a unix-style filepath and does one of three things:

* returns an entity if a suitable one can be found
* returns undef if no entity can be found
* raises an exception if the entity found is unsuitable or if an error occurs

Much of the logic of this method is implemented by an around modifier applied by the role. This modifier will convert paths from strings into arrayrefs of path parts.

Empty path parts are removed -- except for the first, which would represent the root are skipped, and the last, which would imply that you provided a path ending in /, which is a directory.

If the resolver has a converter (see below) then the found entity will be passed to the converter and the result will be returned. Otherwise, the entity will be type-checked and returned.

This means that to write a resolver, you must write a entity_at method that accepts an arrayref of path parts (strings) and returns an object of the type indicated by the resolver's native_type method (below).

native_type

This method should return a Moose::Meta::TypeConstraint indicating the type of entity that will be located by the resolver's native entity_at.

It must be provided by classes implementing the Path::Resolver::Role::Resolver role.

effective_type

This method returns the type that the wrapped entity_at method will return. This means that if there is a converter (see below) it will return the converter's output type. Otherwise, it will return the resolver's native type.

converter

The converter method (actually an attribute) may be undef or may be an object that implements the Path::Resolver::Role::Converter object.

It will be used to convert objects from the resolver's native type to another type.

default_converter

This method can be implemented by resolver classes to set a default converter. The version provided by this role returns false.

To see an example of this put to use, see Path::Resolver::Role::FileResolver.

content_for

  my $content_ref = $resolver->content_for($path);

This method is provided with backward compatibility with previous versions of Path::Resolver. This method will be removed in the near future.

It calls entity_at and then calls the content_ref on the entity. If the entity doesn't provide a content_ref method, an exception will be thrown.

AUTHOR

Top

Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

Top

This software is copyright (c) 2010 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Path-Resolver documentation Contained in the Path-Resolver distribution. 
package Path::Resolver::Role::Resolver;
BEGIN {
  $Path::Resolver::Role::Resolver::VERSION = '3.100451';
}
# ABSTRACT: resolving paths is just what resolvers do!
use Moose::Role;

use namespace::autoclean;

use File::Spec::Unix;
use MooseX::Types;


requires 'entity_at';

around entity_at => sub {
  my ($orig, $self, $path) = @_;
  my @input_path;

  if (ref $path) {
    @input_path = @$path;
  } else {
    Carp::confess("invalid path: empty") unless defined $path and length $path;

    @input_path = File::Spec::Unix->splitdir($path);
  }

  Carp::confess("invalid path: empty") unless @input_path;
  Carp::confess("invalid path: ends with non-filename")
    if $input_path[-1] eq '';

  my @return_path;
  push @return_path, (shift @input_path) if $input_path[0] eq '';
  push @return_path, grep { defined $_ and length $_ } @input_path;

  my $entity = $self->$orig(\@return_path);

  return unless defined $entity;

  if (my $conv = $self->converter) {
    return $conv->convert($entity);
  } else {
    my $native_type = $self->native_type;

    if (my $error = $native_type->validate($entity)) {
      confess $error;
    }

    return $entity;
  }
};


requires 'native_type';


sub effective_type {
  my ($self) = @_;
  return $self->native_type unless $self->converter;
  return $self->converter->output_type;
}


has converter => (
  is      => 'ro',
  isa     => maybe_type( role_type('Path::Resolver::Role::Converter') ),
  builder => 'default_converter',
);


sub default_converter { return }


sub content_for {
  my ($self, $path) = @_;
  return unless my $entity = $self->entity_at($path);

  confess "located entity can't perform the content_ref method"
    unless $entity->can('content_ref');

  return $entity->content_ref;
}

1;

__END__