NAME

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

SYNOPSIS

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

DESCRIPTION

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. This can also be an array reference containing several URLs, whose content will be passed to the extract subroutine.

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.

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.

METHODS

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).

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().

TRANSFORMATION SUBROUTINES

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 (_).

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.

AUTHOR

Philippe 'BooK' Bruhat, <book@cpan.org>.

ACKNOWLEDGEMENTS

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

SEE ALSO

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

COPYRIGHT & LICENSE

Copyright 2005-2006 Philippe 'BooK' Bruhat, All Rights Reserved.

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