NAME
    portable::loader - load classes and roles which can be moved around your
    namespace

SYNOPSIS
    Define some classes:

      ## Nature.portable
      ##
      version = 1.0
      toolkit = "Moo"
  
      [class:Tree.has]
      leaf = { is = "lazy", type = "ArrayRef[Leaf]" }
  
      [class:Tree.can]
      add_leaf = {{{
        my $self = shift;
        push @{ $self->leaf }, @_;
        return $self; # for chaining
      }}}
      _build_leaf = {{{
        return [];
      }}}
  
      [class:Leaf.has]
      colour = { type = "Str", default = "green" }
  
      [class:Maple]
      extends = "Tree"

    Use the classes:

      ## script.pl
      ##
      use portable::lib '/var/lib/portable-libs';
      use portable::alias 'Nature';
  
      my $tree  = Nature->new_maple;
      $tree->add_leaf( Nature->new_leaf );
  
      # 'Nature' isn't really a Perl package.
      # It's just a sub that returns a string.

DESCRIPTION
    The intent of portable::loader is for classes and roles to be portable
    around your namespace. The idea is for classes and roles to not know their
    package names and not care about their package names. And for them to also
    not know or care about the package names of their "friends".

    (When I say their friends, I'm talking about a user-agent object which
    needs to be able to consume HTTP request objects and return HTTP response
    objects, maybe write to a cookie jar object, etc.)

    Typically in Perl code, package names are the one thing that is hard-coded
    everywhere and this can make things like dependency injection, and API
    versioning really difficult to do. Like if you need to make some major
    changes to your class's API, do you create an entirely new package with a
    different namespace, then wait for your consumers to update? Or do you
    keep the old namespace and deal with breakages.

    What if instead of doing this:

      use YourAPI::Tree;
      use YourAPI::Leaf;
  
      my $tree = YourAPI::Tree->new;
      $tree->add_leaf(YourAPI::Leaf->new);

    People could do this?

      use portable::loader;
      my $api = portable::loader->load("YourAPI");
  
      my $tree = $api->new_tree;
      $tree->add_leaf($api->new_leaf);

    The class names are not hard-coded anywhere. They are not even hard-coded
    in the definitions of the Leaf and Tree classes.

    And there's very little runtime overhead in doing this!

  Writing a portable library
   Syntax
    Portable libraries are conceptually any hashref suitable for passing to
    MooX::Press. A structure something like this:

      {
        version => 1.0,
        toolkit => "Moo",
        "class:Tree" => {
          has => [
            "leaf" => { is => "lazy", type => "ArrayRef[Leaf]" },
          ],
          can => [
            "add_leaf" => sub {
              my $self = shift;
              push @{ $self->leaf }, @_;
              return $self; # for chaining
            },
            "_build_leaf" => sub {
              return [];
            },
          ],
        },
        "class:Leaf" => {
          has => [
            "colour" => { type => "Str", default => "green" },
          ],
        },
        "class:Maple" => {
          extends => "Tree",
        },
      }

    You could save that as "Nature.portable.pl" and portable::loader would be
    able to load it.

    But although a library is conceptually a hashref, it can be written in
    other syntaxes. It could be written in JSON, if JSON::Eval is used to
    inflate coderefs in the JSON:

      {
        "version": 1.0,
        "toolkit": "Moo",
        "class:Tree": {
          "has": [
            "leaf": { "is": "lazy", "type": "ArrayRef[Leaf]" }
          ],
          "can": [
            "add_leaf": {
              "$eval": "sub { my $self = shift; push @{ $self->leaf }, @_; return $self; }" 
            },
            "_build_leaf: {
              "$eval": "sub { return []; }"
            }
          ]
        },
        "class:Leaf": {
          "has": [
            "colour": { "type": "Str", "default": "green" }
          ],
        },
        "class:Maple": {
          "extends": "Tree"
        }
      }

    If this is saved at "Nature.portable.json", portable::loader should be
    able to load it.

    The default format that portable::loader uses though, is TOML, an INI-like
    file format. portable::loader adds an extension to TOML allowing `{{{ ...
    }}}` to represent a coderef with Perl code inside. (The parsing is kind of
    naive, so don't expect nested coderefs to work and that kind of thing!

      version = 1.0
      toolkit = "Moo"
  
      [class:Tree.has]
      leaf = { is = "lazy", type = "ArrayRef[Leaf]" }
  
      [class:Tree.can]
      add_leaf = {{{
        my $self = shift;
        push @{ $self->leaf }, @_;
        return $self; # for chaining
      }}}
      _build_leaf = {{{
        return [];
      }}}
  
      [class:Leaf.has]
      colour = { type = "Str", default = "green" }
  
      [class:Maple]
      extends = "Tree"

   Design considerations
    When writing a library, the key thing to remember is that you don't know
    the final package names of any of your classes and roles.

    You can refer to other classes and roles from your library in type
    constraints, and that should "just work".

    Also, you can instantiate other classes in your methods using:

      [class:Maple.can]
      grow_red_leaf = {{{
        my $self = shift;
        my $leaf = $self->FACTORY->new_leaf(colour => "red");
        push @{ $self->leaf }, $leaf;
        return $self;
      }}}

    The `$self->FACTORY` method gives you something with a bunch of `new_*`
    methods for instantiating other objects from your library.

    You could even do this when defining the Leaf class:

      [class:Leaf.factory]
      new_leaf = {{{
        my ($factory, $class) = (shift, shift);
        return $class->new(@_);
      }}}
      new_red_leaf = {{{
        my ($factory, $class) = (shift, shift);
        return $class->new(colour => "red", @_);
      }}}

    And then your Maple class can do this:

      [class:Maple.can]
      grow_red_leaf = {{{
        my $self = shift;
        my $leaf = $self->FACTORY->new_red_leaf;
        push @{ $self->leaf }, $leaf;
        return $self;
      }}}

    The aim being for your Maple class to know as little as possible about how
    to build a leaf other than "I can get one from the factory".

    This makes it easy to override behaviour using Class::Method::Modifiers to
    wrap the `new_red_leaf` method of the factory.

  Loading a library
    portable::loader maintains its own version of @INC to locate libraries
    from: @portable::INC.

    You can use portable::lib to push directories onto it:

      use portable::lib '/var/lib/portable-libs';

    Or you can manipulate @portable::INC directly; it's just an array of
    strings. You should `use portable::lib` first though because portable::lib
    will push some default directories onto @portable::INC before it loads.

    Once you've set your search paths, you can load a library like this:

      use portable::loader;
      my $lib = portable::loader->load($libname);

    portable::loader will search for "$libname.portable.pl",
    "$libname.portable.json", "$libname.portable.toml", or "$libname.portable"
    (which will be assumed to be TOML). Other formats can be supported through
    plugins. (API will eventually be documented.)

    It will be parsed, loaded, classes built, etc, and a string will be
    returned which can be used

    If more than one is found, only one will be loaded. The order in which
    they are checked is currently not guaranteed, but the precedence of
    directories in @portable::INC will be respected.

    There are also `load_from_filename` and `load_from_hashref` methods if you
    already know the exact filename you want to load, or already have a
    hashref.

   Using portable::alias
    This:

      use portable::alias "Foo";

    Is roughly equivalent to this:

      use portable::loader;
      use constant "Foo" => portable::loader->load("Foo");

    This:

      use portable::alias "VeryLongName" => "ShortName";

    Means this:

      use constant "ShortName" => portable::loader->load("VeryLongName");

    So you can do:

      my $thing = Foo->new_someclass(%args);

    The "constant" exported by portable::alias isn't really a constant though.
    It accepts arguments. You can do:

      my $thing = Foo("SomeClass")->new(%args);
  
      my $type_constraint = Foo("SomeClass");
      my $type_constraint = Foo("SomeRole");

    Using portable::alias is a cleaner-looking alternative to using
    portable::loader in a lot of cases.

  Using a library
    Use the factory returned by portable::loader to create objects, then use
    the objects according to the library's documentation.

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=portable-loader>.

SEE ALSO
    MooX::Press, JSON::Eval, TOML, Type::Tiny, Moo, Moose.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2019 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.