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

FreeBSD Manual Pages

  
 
  

home | help
Acme::MetaSyntactic(3)User Contributed Perl DocumentatioAcme::MetaSyntactic(3)

NAME
       Acme::MetaSyntactic - Themed metasyntactic variables names

SYNOPSIS
	   use Acme::MetaSyntactic; # loads the	default	theme
	   print metaname();

	   # this sets the default theme and loads Acme::MetaSyntactic::shadok
	   my $meta = Acme::MetaSyntactic->new(	'shadok' );

	   print $meta->name();		 # return a single name
	   my @names = $meta->name( 4 ); # return 4 distinct names (if possible)

	   # you can temporarily switch	theme
	   # (though it	shifts your metasyntactical paradigm in	other directions)
	   my $foo = $meta->name( 'foo'	);	 # return 1 name from theme foo
	   my @foo = $meta->name( toto => 2 );	 # return 2 names from theme toto

	   # but why would you need an instance	variable?
	   use Acme::MetaSyntactic qw( batman robin );

	   # the first loaded theme is the default (here batman)
	   print metaname;
	   my @names = metaname( 4 );

	   print join ',', metabatman(3), metarobin;

	   # the convenience functions are only	exported
	   # - via the Acme::MetaSyntactic import list
	   # - when an individual theme	is used
	   print join $/, metabatman( 5	);

	   use Acme::MetaSyntactic::donmartin;
	   print join $/, metadonmartin( 7 );

	   # but a one-liner is	even better
	   perl	-MAcme::MetaSyntactic=batman -le 'print	metaname'

	   # the meta(1) command-line tool can be helpful too
	   meta	batman

DESCRIPTION
       When writing code examples, it's	always easy at the beginning:

	   my $foo = "bar";
	   $foo	.= "baz";   # barbaz

       But one gets quickly stuck with the same	old boring examples.  Does it
       have to be this way? I say "No".

       Here is "Acme::MetaSyntactic", designed to fulfill your metasyntactic
       needs.  Never again will	you scratch your head in search	of a good
       variable	name!

METHODS	(& FUNCTIONS)
       "Acme::MetaSyntactic" has an object-oriented interface, but can also
       export a	few functions (see EXPORTS).

   Methods
       If you choose to	use the	OO interface, the following methods are
       available:

       new( $theme )
	   Create a new	instance of "Acme::MetaSyntactic" with the theme
	   $theme.  If $theme is omitted, the default theme is "foo".

       name( [ $theme, ] $count	)
	   Return $count items from theme $theme. If no	theme is given,	the
	   theme is the	one passed to the constructor.

	   If $count is	omitted, it defaults to	1.

	   If $count is	0, the whole list is returned (this may	vary depending
	   on the "behaviour" of the theme) in list context, and the size of
	   the list in scalar context.

       There are also some class methods:

       themes( )
	   Return the sorted list of all available themes.

       has_theme( $theme )
	   Return true if the theme $theme exists.

       add_theme( theme	=> [ @items ], ... )
	   This	class method adds a new	theme to the list. It also creates and
	   exports all the convenience functions ("metatheme()") needed.

	   Note	that this method can only create themes	that implement the
	   "Acme::MetaSyntactic::List" behaviour.

       load_data( $data	)
	   This	method is used by the "behaviour" classes (such	as
	   "Acme::MetaSyntactic::List")	to read	the content of the "DATA"
	   filehandle and fetch	the theme data.

	   The format is very simple. If the "DATA" filehandle contains	the
	   following data:

	       # names
	       bam zowie plonk
	       powie kapow # comment
	       # multi level
		 abc	def
	       # empty
	       # multi lingual
	       fr de

	   "load_data()" will return the following data	structure (the string
	   is trimmed, newlines	and duplicate whitespace characters are
	   squashed, and end-of-line comments are removed):

	       {
		   names => "bam zowie plonk powie kapow",
		   multi => {
		       level   => "abc def",
		       lingual => "fr de",
		   },
		   empty => ""
	       }

	   For example,	"Acme::MetaSyntactic::List" uses the single parameter
	   "names" to fetch the	lists of names for creating its	subclasses.

	   The "init()"	method in all "behaviour" classes will also accept an
	   optional $data hashref and if it provided, will use it instead of
	   reading the "__DATA__" section of the module. The actual structure
	   of the hashref depends on the "Acme::MetaSyntactic::" class.

       Convenience methods also	exists for all the themes. The methods are
       named after the theme. They are exported	only when the theme is
       actually	used or	when it	appear in the "Acme::MetaSyntactic" import
       list. The first imported	theme is the default, used by the "metaname()"
       function.

EXPORTS
       Depending on how	"Acme::MetaSyntactic" is used, several functions can
       be exported. All	of them	behave like the	following:

       metaname( [ $theme, ] $count )
	   Return $count items from theme $theme. If no	theme is given,	the
	   theme is "default" theme. See below how to change what the default
	   is.

   Use cases
       "use Acme::MetaSyntactic;"
	   This	exports	the "metaname()" function only.

       "use Acme::MetaSyntactic	'theme';"
	   This	exports	the "metaname()" function and the "metatheme()"
	   function. "metaname()" default to the theme theme.

       "use Acme::MetaSyntactic	qw(theme1 theme2);"
	   This	exports	the "metaname()", "metatheme1()", "metatheme2()"
	   functions. "metaname()" default to the first	theme of the list
	   (theme1).

       "use Acme::MetaSyntactic	':all';"
	   This	exports	the "metaname()" function and the meta*	functions for
	   all themes. "metaname()" default to the standard default theme
	   ("foo").

       "use Acme::MetaSyntactic::theme;"
	   This	exports	the "metatheme()" function only. The "metaname()"
	   function is not exported.

THEMES
       The list	of available themes can	be obtained with the following one-
       liner:

	   $ perl -MAcme::MetaSyntactic	-le 'print for Acme::MetaSyntactic->themes'

       The themes are all the "Acme::MetaSyntactic::theme" classes, with theme
       starting	with a lowercase letter.

       The items that make up Acme::MetaSyntactic themes are finite lists of
       valid Perl identifiers (not the UTF-8 kind).

   Theme behaviours
       "Acme::MetaSyntactic" provides theme authors with the capability	of
       creating	theme "behaviours". Behaviours are implemented as classes from
       which the individual themes inherit.

       The behaviours are all the "Acme::MetaSyntactic::type" classes, with
       type starting with an uppercase letter.

       Here are	the available behaviours:

       "Acme::MetaSyntactic::List"
	   The theme is	a simple collection of names. An object	instance will
	   return names	at random from the list, and not repeat	any until the
	   list	is exhausted.

       "Acme::MetaSyntactic::Locale"
	   The theme is	made of	several	collections of names, each associated
	   with	a "language". The language is either passed as a constructor
	   parameter, extracted	from the environment or	a default is selected.

       "Acme::MetaSyntactic::MultiList"
	   The theme is	made of	several	collections of names, each associated
	   with	a "category". Categories can include sub-categories, etc, ad
	   infinitum (or when disk space or memory is exhausted, whichever
	   happens first).  The	category is either passed as a constructor
	   parameter or	the default value is selected.

       "Acme::MetaSyntactic::Alias"
	   The theme is	simply an alias	of another theme. All items are
	   identical, as the original behaviour. The only difference is	the
	   theme name.

       Over time, new theme "behaviours" will be added.

SEE ALSO
       Acme::MetaSyntactic::Themes, meta, metafy.

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

BUGS
       Please report any bugs or feature requests to
       "bug-acme-metasyntactic@rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org>.  I	will be	notified, and then you'll
       automatically be	notified of progress on	your bug as I make changes.

       If you think this modules lacks a particular set	of metasyntactic
       variables, please send me a list, as well as a generation algorithm
       (either one of the built-ins ("Acme::MetaSyntactic::List",
       "Acme::MetaSyntactic::Locale"), or a new	one of your invention).

ACKNOWLEDGEMENTS
       Individual contributors are listed in the individual theme files.  Look
       at the included CONTRIBUTORS file for the list of all contributors (43
       in this version).

       However,	this module could not have been	possible without:

       o   Some	sillyness

	   See <http://use.perl.org/~BooK/journal/22301>, the follow-up
	   <http://use.perl.org/~BooK/journal/22710>, and the announce
	   <http://use.perl.org/~BooK/journal/22732>.

       o   The Batman serial from the 60s (it was shown	in France in the 80s).

	   my wife loves it, I name most of my machines	after the bat fight
	   sound effects ("zowie", "klonk", "zlonk"), and I even own a CD of
	   the serial's	theme music and	the DVD	of the movie (featuring	the
	   batboat and the batcopter!).

       o   Rafael Garcia-Suarez,

	   who apparently plans	to use it. Especially now that it's usable in
	   one-liners.

       o   Vahe	Sarkissian,

	   who was the first to	suggest	an additional list (the	sound effects
	   from	Don Martin's comic-books) and provided a link to a
	   comprehensive list.

       o   SA(C)bastien	Aperghis-Tramoni,

	   who actually	uses it, to do what he thinks is the only logical
	   thing to do with "Acme::MetaSyntactic": an IRC bot! See
	   Bot::MetaSyntactic.

	       #perlfr Sat Mar	5 01:15	CET 2005
	       <Maddingue> BooK: bon, l'API de AMS, tu l'as changA(C) alors ?
	       <BooK> je sais pas
	       <Maddingue> comment on fait pour	invoquer ton merder
	       <BooK> ca se mA(C)lange dans ma tete
	       <BooK> je peux te montrer des use case
	       <Maddingue> je veux juste savoir	si tu vas changer la commande meta
	       <Maddingue> BooK: parce que j'ai	fais la	seule chose qui	me semblait
			   logique de faire avec ton module
	       <BooK> un robot irc

       o   JA(C)rA'me Fenal,

	   who wrote Acme::MetaSyntactic::RefactorCode,	which helps
	   "Acme::MetaSyntactic" fulfill its role: rename your boring
	   variables with silly	names.

       o   Abigail,

	   who provided	by himself more	than 35	themes (I stopped counting
	   after that).	 I probably won't be able to include them all before
	   version 1.00.

COPYRIGHT
       Copyright 2005-2017 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-17		Acme::MetaSyntactic(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS (& FUNCTIONS) | EXPORTS | THEMES | SEE ALSO | AUTHOR | BUGS | ACKNOWLEDGEMENTS | COPYRIGHT | LICENSE

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

home | help