Acme::MetaSyntactic::RemoteList






Acme::MetaSyntactic::RemoteList − Retrieval of a remote
source for a theme


    package Acme::MetaSyntactic::contributors;
    use strict;
    use Acme::MetaSyntactic::List;
    our @ISA = qw( Acme::MetaSyntactic::List );

    # data regarding the remote source
    our %Remote = (
        source =>
            'http://search.cpan.org/dist/Acme−MetaSyntactic/CONTRIBUTORS',
        extract => sub {
            my $content = shift;
            my @items   =
                map { Acme::MetaSyntactic::RemoteList::tr_nonword($_) }
                map { Acme::MetaSyntactic::RemoteList::tr_accent($_) }
                $content =~ /^\* (.*?)\s*$/gm;
            return @items;
        },
    );

    __PACKAGE__−>init();

    1;

    # and the usual documentation and list definition

This base class adds the capability to fetch a fresh list of
items from a remote source to any theme that requires it.

     To be able to fetch remote items, an
"Acme::MetaSyntactic" theme must define the package hash
variable %Remote with the appropriate keys.

     The keys are:

"source"
    The URL where the data is available. The content will be
    passed to the "extract" subroutine.

    Because of the various way the data can be made
    available on the web and can be used in
    Acme::MetaSyntactic, this scheme has evolved to support
    several cases:

    Single source URL:

        source => $url

    Multiple source URL:

        source => [ $url1, $url2, ... ]









                             ‐2‐


    For themes with categories, it’s possible to attach a
    URL for each category:

        source => {
            category1 => $url1,
            category2 => $url2,
            ...
        }

    In the case where the "source" is an array or a hash
    reference, an extra case is supported, in case the
    source data can only be obtained via a "POST" request.
    In that case, the source should be provided as either:

        source => [
            [ $url1 => $data1 ],
            [ $url2 => $data2 ],
            ...
        ]

    or

        source => {
            category1 => [ $url1 => $data1 ],
            category2 => [ $url2 => $data2 ],
            ...
        }

    It is possible to mix "POST" and "GET" URL:

        source => [
            $url1,                  # GET
            [ $url2 => $data2 ],    # POST
            ...
        ]

    or

        source => {
            category1 => $url1,                  # GET
            category2 => [ $url2 => $data2 ],    # POST
            ...
        }

    This means that even if there is only one source and a
    "POST" request must be used, then it must be provided as
    a list of a single item:

        source => [ [ $url => $data ] ]

"extract"
    A reference to a subroutine that extracts a list of
    items from a string.  The string is meant to be the
    content available at the URL stored in the "source" key.









                             ‐3‐


    The coderef may receive an optional parameter
    corresponding to the name of the category (useful if the
    coderef must behave differently depending on the
    category).

     "LWP::Simple" is used to download the remote data.

     All existing "Acme::MetaSyntactic" behaviours
("Acme::MetaSyntactic::List" and
"Acme::MetaSyntactic::Locale" are subclasses of
"Acme::MetaSyntactic::RemoteList".

As an ancestor, this class adds the following methods to an
"Acme::MetaSyntactic" theme:

remote_list()
    Returns the list of items available at the remote
    source, or an empty list in case of error.

has_remotelist()
    Return a boolean indicating if the "source" key is
    defined (and therefore if the theme actually has a
    remote list).

source()
    Return the data structure containing the source URLs.
    This can be quite different depending on the class: a
    single scalar (URL), an array reference (list of URLs)
    or a hash reference (each value being either a scalar or
    an array reference) for themes that are subclasses of
    "Acme::MetaSyntactic::MultiList".

sources( [ $category ] )
    Return the list of source URL. The $category parameter
    can be used to select the sources for a sub‐category of
    the theme (in the case of
    "Acme::MetaSyntactic::MultiList").

    $category can be an array reference containing a list of
    categories.

extract( $content )
    Return a list of items from the $content string.
    $content is expected to be the content available at the
    URL given by "source()".

The "Acme::MetaSyntactic::RemoteList" class also provides a
few helper subroutines that simplify the normalisation of
items:

tr_nonword( $str )
    Return a copy of $str with all non‐word characters
    turned into underscores ("_").










                             ‐4‐


tr_accent( $str )
    Return a copy of $str will all iso−8859−1 accented
    characters turned into basic ASCII characters.

tr_utf8_basic( $str )
    Return a copy of $str with some of the utf−8 accented
    characters turned into basic ASCII characters. This is
    very crude, but I didn’t to bother and depend on the
    proper module to do that.

Philippe ’BooK’ Bruhat, "<book@cpan.org>".

Thanks to Michael Scherer for his help in finding the name
of this module on "#perlfr". Welcome in CONTRIBUTORS,
Michael! ":−)"

         #perlfr Tue Nov  1 19:33 CET 2005
    <@BooK> bon, je sais toujours pas comment appeler mon module moi
    <@BooK> AMS::RemoteSource ?
    < misc> RemoteListing ?
    <@BooK> RemoteList, même

Acme::MetaSyntactic, Acme::MetaSyntactic::List,
Acme::MetaSyntactic::Locale.

Copyright 2005−2012 Philippe ’BooK’ Bruhat, All Rights
Reserved.