gitpan / cpan-cache Goto Github PK

NAME
    CPAN::Cache - Abstract locally-cached logical subset of a CPAN mirror

DESCRIPTION
    There have been any number of scripts and modules written that contain
    as part of their functionality some form of locally stored partial
    mirror of the CPAN dataset.

    CPAN::Cache does the same thing, except that in addition it has the
    feature that the downloading and storage of CPAN data is all that it
    does, so it should not introduce any additional dependencies or bloat,
    and should be much easier to reuse that existing modules, which
    generally are more task-specific.

    The intent is that this module will be usable by everything that is in
    the business of pulling modules from CPAN, storing them locally, and
    doing something with them.

    In this way, it really does little other than mirror data from a remote
    URI, except that CPAN::Cache also provides some additional intelligence
    about which files are and are not static (will never change) which
    aren't, and is typed specifically as a mirror of CPAN, instead of any
    other sort of mirror.

    By building this module as a seperate distribution, it is hoped we can
    improve seperation of concerns in the CPAN-related modules and ensure
    cleaner, smaller, and more robust tools that interact with the CPAN in
    the most correct ways.

METHODS
  new
      my $cache = CPAN::Cache->new(
          remote_uri => 'http://search.cpan.org/CPAN/',
          local_dir  => '/tmp/cpan',
          );

  remote_uri
    The "remote_uri" accessor returns a URI object for the remote CPAN
    repository.

  local_dir
    The "local_dir" accessor returns the filesystem path for the root root
    directory of the CPAN cache.

  file path/to/file.txt
    The "file" method takes the path of a file within the repository, and
    returns a URI::ToDisk object representing it's location on both the
    server, and on the local filesystem.

    Paths should always be provided in unix/web format, not the local
    filesystem's format.

    Returns a HTML::ToDisk or throws an exception if passed a bad path.

  get path/to/file.txt
    The "get" method takes the path of a file within the repository, and
    fetches it from the remote repository, storing it at the appropriate
    local path.

    Paths should always be provided in unix/web format, not the local
    filesystem's format.

    Returns the URI::ToDisk for the file if retrieved successfully, false
    false if the file does not exist within the repository, or throws an
    exception on error.

  mirror path/to/file.txt
    The "mirror" method takes the path of a file within the repository, and
    mirrors it from the remote repository, storing it at the appropriate
    local path.

    Using this method if preferable for items like indexs for which want to
    ensure you have the current version, but do not want to freshly download
    each time.

    Paths should always be provided in unix/web format, not the local
    filesystem's format.

    Returns the URI::ToDisk for the file if mirrored successfully, false if
    the file did not exist in the repository, or throws an exception on
    error.

  static
    The "static" method determines whether a given path within CPAN is able
    to change or not.

    In the CPAN, some files such as index files and checksum can change,
    while other files such as the tarball files will be static, and once
    committed to the repository will never be changed (altough they may be
    deleted).

    In a caching scenario, this means that if the file exists locally, we
    will never need to return to the server to check for a new version, we
    enables additional optimisations for CPAN-related algorithms.

    Returns true if the file will never change, false if not, or throws an
    exception on error.

TO DO
    - Write a proper test suite, not just a compile test (even though this
    was taken from working JSAN code)

SUPPORT
    Bugs should be reported via the CPAN bug tracker

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN-Cache>

    For other issues, contact the author.

AUTHOR
    Adam Kennedy <[email protected]>

SEE ALSO
    CPAN::Index, CPAN::Mini, DBIx::Class

COPYRIGHT
    Copyright 2006 Adam Kennedy.

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

    The full text of the license can be found in the LICENSE file included
    with this module.