Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Acme::MetaSyntactic::RUsereContributed Perl Acme::MetaSyntactic::RemoteList(3)

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.	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, ... ]

	   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.

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

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

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

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, mAame

SEE ALSO
       Acme::MetaSyntactic, Acme::MetaSyntactic::List,
       Acme::MetaSyntactic::Locale.

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

LICENSE	This program is	free software; you can redistribute it and/or modify
       it under	the same terms as Perl itself.
perl v5.24.1			  2017-04-17Acme::MetaSyntactic::RemoteList(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | TRANSFORMATION SUBROUTINES | AUTHOR | ACKNOWLEDGEMENTS | SEE ALSO | COPYRIGHT | LICENSE This program is free software; you can redistribute it and/or modify

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Acme::MetaSyntactic::RemoteList&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help