GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Data::Remember(3) User Contributed Perl Documentation Data::Remember(3)

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

version 0.140490

  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 / ]

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.

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

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:

  • Data::Remember::Memory
  • Data::Remember::DBM
  • Data::Remember::YAML
  • Data::Remember::Hybrid
  • 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 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.

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

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.

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.
  • 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.
  • Array. For arrays, the iterator will return each index and value as a pair, in order.
  • 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.

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';

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.

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.

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;

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.

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.

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

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

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.

2014-02-18 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.