NAME
Path::Resolver::Role::Resolver - resolving paths is just what resolvers do!
VERSION
version 3.100455
DESCRIPTION
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.
PERL VERSION
This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.
Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.
METHODS
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
Ricardo Signes <cpan@semiotic.systems>
COPYRIGHT AND LICENSE
This software is copyright (c) 2022 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.