NAME
    Gentoo::Overlay - Tools for working with Gentoo Overlays

VERSION
    version 2.001001

SYNOPSIS
      my $overlay = Gentoo::Overlay->new( path => '/usr/portage' );

      my $name       = $overlay->name();
      my %categories = $overlay->categories();

      print "Overlay $name 's categories:\n";
      for( sort keys %categories ){
        printf "%30s : %s", $_, $categories{$_};
      }

      # Overlay gentoo 's categories:
      #  .....
      #  dev-lang      : /usr/portage/dev-lang
      #  .....

    There will be more features eventually, this is just a first release.

METHODS
  default_path
    Useful function to easily wrap the class-wide method with a per-object
    sugar.

        $overlay->default_path('profiles');
        ->
        ::Overlay->_default_paths->{'profiles'}->($overlay);
        ->
        $overlay->path->subdir('profiles')


        $overlay->default_path('category','foo');
        ->
        ::Overlay->_default_path('category')->( $overlay, 'foo' );
        ->
        $overlay->path->subdir('foo')

        $overlay->default_path('repo_name');
        ->
        ::Overlay->_default_path('repo_name')->( $overlay );
        ->
        $overlay->_profile_dir->file('repo_name')

    They're class wide functions, but they need individual instances to
    work.

  iterate
      $overlay->iterate( $what, sub {
          my ( $context_information ) = shift;

      } );

    The iterate method provides a handy way to do walking across the whole
    tree stopping at each of a given type.

    *   "$what = 'categories'"

          $overlay->iterate( categories => sub {
              my ( $self, $c ) = shift;
              # $c->{category_name}  # String
              # $c->{category}       # Category Object
              # $c->{num_categories} # How many categories are there to iterate
              # $c->{last_category}  # Index ID of the last category.
              # $c->{category_num}   # Index ID of the current category.
          } );

    *   "$what = 'packages'"

          $overlay->iterate( packages => sub {
              my ( $self, $c ) = shift;
              # $c->{category_name}  # String
              # $c->{category}       # Category Object
              # $c->{num_categories} # How many categories are there to iterate
              # $c->{last_category}  # Index ID of the last category.
              # $c->{category_num}   # Index ID of the current category.
              #
              # $c->{package_name}   # String
              # See ::Category for the rest of the fields provided by the package Iterator.
              # Very similar though.
          } );

    *   "$what = 'ebuilds'"

          $overlay->iterate( ebuilds => sub {
              my ( $self, $c ) = shift;
              # $c->{category_name}  # String
              # $c->{category}       # Category Object
              # $c->{num_categories} # How many categories are there to iterate
              # $c->{last_category}  # Index ID of the last category.
              # $c->{category_num}   # Index ID of the current category.
              #
              # $c->{package_name}   # String
              # See ::Category for the rest of the fields provided by the package Iterator.
              # Very similar though.
              #
              # $c->{ebuild_name}   # String
              # See ::Package for the rest of the fields provided by the ebuild Iterator.
              # Very similar though.
          } );

ATTRIBUTES
  path
    Path to repository.

        isa => File, ro, required, coerce

    "File" in Types::Path::Tiny

  name
    Repository name.

        isa => Gentoo__Overlay_RepositoryName, ro, lazy_build

    "RepositoryName"

    "_build_name"

ATTRIBUTE ACCESSORS
  category_names
    Returns a list of the names of all the categories.

        my @list = sort $overlay->category_names();

    "_categories"

  categories
    Returns a hash of "Category" objects.

        my %hash = $overlay->categories;
        print $hash{dev-perl}->pretty_name; # dev-perl/::gentoo

    "_categories"

  get_category
    Returns a Category Object for a given category name

        my $cat = $overlay->get_category('dev-perl');

    "_categories"

PRIVATE ATTRIBUTES
  _profile_dir
    Path to the profile sub-directory.

        isa => Dir, ro, lazy_build

    "Dir" in MooseX::Types::Path::Tiny

    "_build__profile_dir"

  _categories
    The auto-generating category hash backing

        isa => HashRef[ Gentoo__Overlay_Category ], ro, lazy_build

    "_build__categories"

    "_has_category"

    "category_names"

    "categories"

    "get_category"

    "Gentoo__Overlay_Category" in Gentoo::Overlay::Types

    "MooseX::Types::Moose"

PRIVATE ATTRIBUTE ACCESSORS
  _has_category
    Returns if a named category exists

        $overlay->_has_category("dev-perl");

    "_categories"

PRIVATE CLASS ATTRIBUTES
  _default_paths
    Class-wide list of path generators.

        isa => HashRef[ CodeRef ], ro, lazy_build

    "_build__default_paths"

PRIVATE METHODS
  _build_name
    Extracts the repository name out of the file '"repo_name"' in
    "$OVERLAY/profiles/repo_name"

        $overlay->_build_name

    "name"

  _build__profile_dir
    Verifies the existence of the profile directory, and returns the path to
    it.

        $overlay->_build__profile_dir

    "_profile_dir"

  _build__categories
    Generates the Category Hash-Table, either by reading the categories
    index ( new, preferred ) or by traversing the directory ( old,
    discouraged )

        $category->_build_categories;

    "_categories"

    "_build___categories_scan"

    "_build___categories_file"

  _build___categories_file
    Builds the category map using the 'categories' file found in the
    overlays profile directory.

        $overlay->_build___categories_file

  _build___categories_scan
    Builds the category map the hard way by scanning the directory and then
    skipping things that are files and/or blacklisted.

        $overlay->_build___categories_scan

  _iterate_ebuilds
      $object->_iterate_ebuilds( ignored_value => sub {  } );

    Handles dispatch call for

      $object->iterate( ebuilds => sub { } );

  _iterate_categories
      $object->_iterate_categories( ignored_value => sub {  } );

    Handles dispatch call for

      $object->iterate( categories => sub { } );

  _iterate_packages
      $object->_iterate_packages( ignored_value => sub {  } );

    Handles dispatch call for

      $object->iterate( packages => sub { } );

AUTHOR
    Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Kent Fredric <kentnl@cpan.org>.

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