NAME
    Pinto - Perl archive repository manager

VERSION
    version 0.005

DESCRIPTION
    You probably want to look at the documentation for pinto. This is a
    private module (for now) and the interface is subject to change. So the
    API documentation is purely for my own reference. But this document does
    explain what Pinto does and why it exists, so feel free to read on
    anyway.

    This is a work in progress. Comments, criticisms, and suggestions are
    always welcome. Feel free to contact "thaljef@cpan.org".

METHODS
  create()
    Creates a new empty repository.

  mirror()
    Populates your repository with the latest version of all packages found
    on the CPAN mirror. Your locally added packages will always mask those
    pulled from the mirror.

  add(file => 'YourDist.tar.gz', author => 'SOMEONE')
  remove(package => 'Some::Package', author => 'SOMEONE')
  clean()
  list()
  verify()
TERMINOLOGY
    Some of the terms around CPAN are frequently misused. So for the purpose
    of this document, I am going to define some terms. I am not saying that
    these are necessarily the "correct" definitions, but this is what I mean
    when I use them.

    package
        A "package" is the name that appears in a "package" statement. This
        is what PAUSE indexes, and this is what you usually ask cpan or
        cpanm to install for you.

    module
        A "module" is the name that appears in a "use" or (sometimes)
        "require" statement, and it always corresponds to a physical file
        somewhere. A module usually contains only one package, and the name
        of the module usually matches the name of the package. But
        sometimes, a module may contain many packages with completely
        arbitrary names.

    archive
        An "archive" is a collection of Perl modules that have been packaged
        in a particular structure. This is what you get when you run ""make
        dist"" or "./Build dist". Archives may come from a "mirror", or you
        may create your own. An archive is the "A" in "CPAN".

    repository
        A "repository" is a collection of archives that are organized in a
        particular structure, and having an index describing which packages
        are contained in each archive. This is where cpan and cpanm get the
        packages from.

    mirror
        A "mirror" is a copy of a public CPAN repository (e.g.
        http://cpan.perl.org). Every "mirror" is a "repository", but not
        every "repository" is a "mirror".

RULES
    There are certain rules that govern how the indexes are managed. These
    rules are intended to ensure that folks pulling packages from your
    repository will always get the *right* packages (according to my
    definitionof "right"). Also, the rules attempt to make Pinto behave
    somewhat like PAUSE does.

    A local package always masks a mirrored package, and all other packages
    that are in the same archive with the mirrored package.
        This rule is key, so pay attention. If the CPAN mirror has an
        archive that contains both "Foo" and "Bar" packages, and you add
        your own archive that contains "Foo" package, then both the "Foo"
        and "Bar" mirroed packages will be removed from your index. This
        ensures that anyone pulling packages from your repository will
        always get *your* version of "Foo". But as a result, they'll never
        be able to get "Bar".

    You can never add an archive with the same name twice.
        Most archive-building tools will put some kind of version number in
        the name of the archive, so this is rarely a problem.

    Only the original author of a local package can add a newer version of
    it.
        Ownership is given on a first-come basis, just like PAUSE. So if
        "SALLY" is the first author to add local package "Foo::Bar" to the
        repository, then only "SALLY" can ever add that package again.

    Only the original author of a local package can remove it.
        Just like when adding new versions of a local package, only the
        original author can remove it.

WHY IS IT CALLED "Pinto"
    The term "CPAN" is heavily overloaded. In some contexts, it means the
    CPAN module or the cpan utility. In other contexts, it means a mirror
    like <http://cpan.perl.org> or a site like <http://search.cpan.org>.

    I wanted to avoid confusion, so I picked a name that has no connection
    to "CPAN" at all. "Pinto" is a nickname that I sometimes call my son,
    Wesley.

TODO
    Enable plugins for visiting and filtering
    Implement Pinto::Store::Git
    Fix my Moose abuses
    Consider storing indexes in a DB, instead of files
    Automatically fetch dependecies when adding *VERY COOL*
    New command for listing conflicts between local and mirrored index
    Make file/directory permissions configurable
    Refine terminology: consider "distribution" instead of "archive"
    Need more error checking and logging
    Lots of tests to write

THANKS
    Randal Schwartz - for pioneering the first mini CPAN back in 2002
    Ricardo Signes - for creating CPAN::Mini, which inspired much of Pinto
    Shawn Sorichetti & Christian Walde - for creating CPAN::Mini::Inject

SUPPORT
  Perldoc
    You can find documentation for this module with the perldoc command.

      perldoc Pinto

  Websites
    The following websites have more information about this module, and may
    be of help to you. As always, in addition to those websites please use
    your favorite search engine to discover more resources.

    *   Search CPAN

        The default CPAN search engine, useful to view POD in HTML format.

        <http://search.cpan.org/dist/Pinto>

    *   RT: CPAN's Bug Tracker

        The RT ( Request Tracker ) website is the default bug/issue tracking
        system for CPAN.

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pinto>

    *   CPAN Ratings

        The CPAN Ratings is a website that allows community ratings and
        reviews of Perl modules.

        <http://cpanratings.perl.org/d/Pinto>

    *   CPAN Testers

        The CPAN Testers is a network of smokers who run automated tests on
        uploaded CPAN distributions.

        <http://www.cpantesters.org/distro/P/Pinto>

    *   CPAN Testers Matrix

        The CPAN Testers Matrix is a website that provides a visual way to
        determine what Perls/platforms PASSed for a distribution.

        <http://matrix.cpantesters.org/?dist=Pinto>

    *   CPAN Testers Dependencies

        The CPAN Testers Dependencies is a website that shows a chart of the
        test results of all dependencies for a distribution.

        <http://deps.cpantesters.org/?module=Pinto>

  Bugs / Feature Requests
    Please report any bugs or feature requests by email to "bug-pinto at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pinto>. You will be
    automatically notified of any progress on the request by the system.

  Source Code
    <https://github.com/thaljef/Pinto>

      git clone https://github.com/thaljef/Pinto

AUTHOR
    Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Imaginative Software Systems.

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

