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

FreeBSD Manual Pages

  
 
  

home | help
Data::Remember(3)     User Contributed Perl Documentation    Data::Remember(3)

NAME
       Data::Remember -	remember complex information without giving yourself a
       headache

VERSION
       version 0.140490

SYNOPSIS
	 use Data::Remember 'Memory';

	 remember foo => 1;
	 remember [ bar	=> 7 ],	[ 'spaz', 'w00t', 'doof', 'flibble' ];
	 remember [ 'xyz', 'abc', 'mno'	] => { some => 'thing' };

	 remember_these	cook =>	'goose';
	 remember_these	cook =>	'duck';
	 remember_these	cook =>	'turkey';

	 my $foo     = recall 'foo';	    # retrieve a simple	key
	 my $wibbler = recall [	bar => 7 ]; # retrieve a complex key
	 my $alpha   = recall 'xyz';	    # retrieve a subkey

	 my $cook    = recall [	'cook' ];   # retrieves	[ qw/ goose duck turkey	/ ]

	 forget	'foo';

	 my $foo_again = recall	'foo'; # $foo_again is undef

	 forget_when { /^duck$/	} [ 'cook' ];

	 my $cook_again	= recall 'cook'; # $cook_again is [ qw/	goose turkey / ]

DESCRIPTION
       This is the original interface, but the preferred implementation	is now
       Data::Remember::Class. This is now just a functional wrapper around
       that interface.

       See Data::Remember::Class for more documentaiton.

SUBROUTINES
       By using	this module you	will automatically import (I know, how rude)
       four subroutines	into the calling package: "remember",
       "remember_these", "recall", "recall_and_update",	"forget", forget_when,
       and "brain".

   import $brain, @options;
       Called automagically when you "use" this	package. Do NOT	try

	 use Data::Remember ();

       This will keep import from being	called,	which will keep	you from using
       any of the nice features	of this	package. Since it uses deep magic in
       the import process, attempting to call "Data::Remember::remember()" and
       such won't work correctly.

       If you can't import these methods, sorry. Send me a bug report and a
       patch and I'll consider it.

       The $brain argument lets	you select a brain plugin to use. The brain
       plugins available with this distribution	currently include:

       o   Data::Remember::Memory

       o   Data::Remember::DBM

       o   Data::Remember::YAML

       o   Data::Remember::Hybrid

       o   Data::Remember::POE

       You can specify $brain as a short name if it exists under
       ""Data::Remember::"". (For example, ""DBM"" will	load
       ""Data::Remember::DBM"".) if $brain contains a ""::"", then it will be
       treated as a fully qualified name, in case you want to create your own
       brain. See "CREATING A BRAIN".

       The @options are	whatever options described in the brain's module
       documentation.

   remember $que, $fact
       Remember	the given $fact	at memory que $que. See	"QUE" in
       Data::Remember::Class for an in depth discussion	of $que. The $fact can
       be anything your	brain can store. This will generally include, at
       least, scalars, hash references,	and array references.

   remember_these $que,	$fact
       Stores the given	$fact at the give $que,	but stores it by pushing it
       onto the	back of	an array stored	at $que. This allows you to remember a
       list of things at a given $que:

	 remember_these	stooges	=> 'Larry';
	 remember_these	stooges	=> 'Curly';
	 remember_these	stooges	=> 'Moe';

	 my $stooges = recall 'stooges'; # returns the array [ qw( Larry Curly Moe ) ]

   recall $que
       Recalls a previously stored fact	located	at the memory location
       described by $que. See "QUE" in Data::Remember::Class for an in depth
       discussion of that argument.

       If no fact is found at that que,	"undef"	will be	returned.

   recall_each $que
       Returns an iterator that	can be used to iterate over all	the facts
       stored under $que. See "QUE" in Data::Remember::Class for more
       information on the que. The way the iterator works will depend on what
       kind of data $que points	to.

       o   Hash. For hashes, the iterator will work similar to the built-in
	   "each" operator. It will return each	key/value pair found in	the
	   hash	in no particular order.

       o   Array. For arrays, the iterator will	return each index and value as
	   a pair, in order.

       o   Scalar. For anything	else, it will return a single pair. The	first
	   element in the pair will be "undef" and the second will be the
	   scalar value.

       When the	iterator is finished it	returns	an empty list.

       The iterator captures the keys and array	length at the time it was
       created.	If changes are made to the data	stored,	it will	return the
       same keys or array indexes that were stored at the moment of the	call,
       but the values returned will be whatever	is current stored. If the
       value at	the que	is removed entirely, the iterator closes over the
       original	reference and will proceed anyway.

   recall_and_update { ... } $que
       This helper allows you to simultaneously	recall and update an entry.
       For example, if you want	to increment the entry while recalling it:

	 my $count = recall_and_update { $_++ }	'count';

       any modification	to $_ will be stored back into the given que. The
       result of the code run is returned by the function. For example,	if you
       wanted to replace every "G" with	"Q" in the brain, but wanted to	use
       the original unmodified string, you could:

	 my $with_g = recall_and_update	{ my $copy = $_; s/G/Q/g; $copy	} 'some_que';

   forget $que
       Tells the brain to forget a previously remembered fact stored at	$que.
       See "QUE" in Data::Remember::Class for an in depth discussion of	the
       argument. If no fact is stored at the given $que, this subroutine does
       nothing.

   forget_when { ... } $que
       Tells the brain to forget a previously remembered fact stored at	$que.
       The behavior of "forget_when" changes depending on the nature of	the
       fact stored at $que.

       If $que is a hash, the code reference given as the first	argument will
       be called for each key/value pair and passed the	key in $_[0] and the
       value in	$_[1]. When the	code reference returns true, that pair will be
       forgotten.

       If $que is an array, the	code reference given as	the first argument
       will be called for each index/value pair	and passed the index in	$_[0]
       and the value in	$_[1], the value will be passed	in $_ as well. If the
       code reference returns a	true value, that value will be forgotten.

       For any other type of fact stored in the	brain, the code	reference will
       be called with $_[0] set	to "undef" and $_[1] and $_ set	to the value
       of the fact. The	whole que will be forgotten if the code	reference
       returns true.

   brain
       Returns the inner object	used to	store data. This can be	used in	case
       the brain plugin	provides additional methods or features	that need
       manual access. For example, if you want to use DBM::Deeps locking
       features, you could:

	 brain->dbm->begin_work;

	 my $balance = recall 'balance';
	 remember balance => $balance +	150;

	 brain->dbm->commit;

CREATING A BRAIN
       If you would like to create a custom brain plugin, you need to create a
       package that implements four methods: "new", "remember",	"recall", and
       "forget".

       The "new" method	will take the list of options passed to	"import" for
       your brain in addition to the class name. It should return a blessed
       reference that will be used for all further method calls.

       The "remember" method will be passed a normalized reference to a	que
       array and the fact the user has asked to	store. You should read through
       "QUE" in	Data::Remember::Class and handle the first argument as
       described there.	Then, store the	second argument	at the memory location
       described.

       The "recall" method will	be passed a normalized reference to a que
       array, which should be treated as described in "QUE" in
       Data::Remember::Class. Your implementation should return	the fact
       stored at that location or "undef". It's	important that your
       implementation avoid the	pit-falls caused by auto-vivifying keys. The
       "recall"	method should never modify the memory of your brain.

       The "forget" method will	be passed a normalized reference to a que
       array, which should be treated as described in "QUE" in
       Data::Remember::Class. Your implementation should then delete any fact
       stored there. Other than	deleting this key, the "forget"	method should
       not modify any other aspect of the memory of your brain.

       To build	a brain, I highly recommend extending Data::Remember::Memory,
       which performs (or should perform) all the work of safely storing and
       fetching	records	from a Perl data structure according to	the interface
       described here. It stores everything under "$self->{brain}". At the
       very least, you should read through that	code before building your
       brain.

       The Data::Remember::DBM or other	included brains	may also be a good
       place to	look. They extend Data::Remember::Memory so that I didn't have
       to repeat myself.

DIAGNOSTICS
       This class emits	the following warnings:

       The brain BRAIN may not have loaded correctly: ERROR
	   This	message	indicates that an error	occurred while loading the
	   package named "BRAIN". "ERROR" contains the nested error message.
	   This	is only	a warning because it's possible	that this failure is
	   normal (e.g., if the	package	is not defined in it's own Perl
	   module).

       Undefined que element used in call to SUB.
	   This	message	indicates that you attempted to	pass an	undefined
	   value as a component	of the que to the named	subroutine. Such calls
	   are ignored by Data::Remember. (Hence the warning.)

       Whenever	possible, this library attempts	not to throw exceptions. The
       major exception that rule (HAH!)	is during initialization. Any problems
       detected	there are generally very important, so exceptions are thrown
       liberally.

       Here are	the exceptions that are	emitted	by this	class:

       This does not look like a valid brain: BRAIN
	   The brain plugin name given does not	look like a valid Perl class
	   name. Data::Remember	won't even check to see	if it is a brain
	   plugin unless it could be a package name.

       Your brain cannot remember facts: BRAIN
	   You attempted to use	a brain	class that does	not provide a
	   "remember()"	method.

       Your brain cannot recall	facts: BRAIN
	   You attempted to use	a brain	class that does	not provide a
	   "recall()" method.

       Your brain cannot forget	facts: BRAIN
	   You attempted to use	a brain	class that does	not provide a
	   "forget()" method.

SEE ALSO
       Data::Remember::Memory, Data::Remember::DBM, Data::Remember::YAML,
       Data::Remember::Hybrid

AUTHOR
       Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2014 by Qubling Software LLC.

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

perl v5.32.0			  2014-02-18		     Data::Remember(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SUBROUTINES | CREATING A BRAIN | DIAGNOSTICS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help