MMAgic::Data Class Reference

MMAgic::Data - Data object stored as file in Perl data structure. More...

List of all members.

Public Member Functions
	_arg ($arg, $init, $dflt)
	Look for intialization parameter.
	new ($path,%init)
	Constructor for MMAgic::Data object.
	DESTROY ()
	Destructor for MMAgic::Data object.
	cleanup ()
	Cleanup open file and locks.
	handle ($writable)
	Open file, return file handle.
	_load ($handle)
	Load and return data from file open on handle.
	fetch ()
	Fetch data value itself.
	flush ()
	Update current value to backing store.
	loaded ()
	Return load time if data currently loaded.
	lock ()
	Lock for (reading and) writing preparatory to making changes.
	path ()
	Return the path of the file containing the underlying data.
	refresh ()
	Cause underlying data to be refreshed.
	store ($data)
	Store data into backing file.
	unlock ()
	Release lock on tied object.
	upToDate ()
	Return true if the data is current.
	TIESCALAR ()
	TIEARRAY ()
	CLEAR ()
	DELETE ()
	EXISTS ()
	EXTEND ()
	FETCHSIZE ()
	POP ()
	PUSH ()
	SHIFT ()
	SPLICE ()
	STORESIZE ()
	UNSHIFT ()
	FETCH ()
	STORE ()
	UNTIE ()

---

Detailed Description

MMAgic::Data - Data object stored as file in Perl data structure.

SYNOPSIS

  my  $data;
  tie $data, 'MMAgic::Data', '/tmp/some.data';
  
  print $data->{field}->[0], "\n";
  if ( $somethingHasChanged && tied($var)->lock)
      {
      my  $temp = $data;  # cause re-read
      # ...statements...  # make changes
      $data->flush;       # push changes out
      }

ABSTRACT

Tie variable to contents of data file expressed as Perl data structure. Fetch and store entire contents. Use non-tie methods lock() and flush() to update parts of the data structure.

DESCRIPTION

CAVEATS

ARRAY

An attempt was made to add an ARRAY tie but it doesn't work very well. Maybe someday...

Opcodes

The Safe module uses opcodes that have changed over time. Current code is working for Perl 5.8.8. It will work as far back as 5.006 but may require different opcodes. The allw flag in the constructor or $ENV{MMAgic_Data_allw} can be used to override the opcodes.

When opcode issues arise, it is often difficult to figure out which opcodes to add. One way is to look up the opcode.h file in the Perl source and cross-reference PL_op_desc[] (which is what shows up in error messages at run-time) to PL_op_name[] (which is what is required for opcode names in the allw list) by array index.

COPYRIGHT AND LICENSE

Copyright 2001-2008 by Marc M. Adkins

Author:

Marc M. Adkins, mailto:Perl@Doorways.org

Definition at line 68 of file Data.pm.

---

Member Function Documentation

MMAgic::Data::_arg	(	$	arg,
		$	init,
		$	dflt
	)

Look for intialization parameter.

Check in $init value, then environment variable of the form $ENV{"MMAgic_Data_$arg}, then $dflt value.

Intended for internal use.

MMAgic::Data::_load

(

$

handle

)

Load and return data from file open on handle.

Default version does an eval on the file contents protected by a Safe object with only basic opcodes allowed.

Intended for internal use.

MMAgic::Data::cleanup

(

)

Cleanup open file and locks.

Intended for internal use.

MMAgic::Data::CLEAR

(

)

MMAgic::Data::DELETE

(

)

MMAgic::Data::DESTROY

(

)

Destructor for MMAgic::Data object.

Invokes cleanup() routine.

MMAgic::Data::EXISTS

(

)

MMAgic::Data::EXTEND

(

)

MMAgic::Data::fetch

(

)

Fetch data value itself.

Value is a scalar reference.

MMAgic::Data::FETCH

(

)

MMAgic::Data::FETCHSIZE

(

)

MMAgic::Data::flush

(

)

Update current value to backing store.

If it fails, the data remains the same.

MMAgic::Data::handle

(

$

writable

)

Open file, return file handle.

Intended for internal use.

MMAgic::Data::loaded

(

)

Return load time if data currently loaded.

MMAgic::Data::lock

(

)

Lock for (reading and) writing preparatory to making changes.

Next read from variable will return new data. Return true if successful, undef on failure.

Call using:

  tied($data)->lock;

Note that file is also opened now!!!

MMAgic::Data::new	(	$	path,
		%	init
	)

Constructor for MMAgic::Data object.

  Flags:      (default)   (description)
  ----------------------------------------------------------------------
    * allw     (below)    allowable operations during file eval
    * barf        1       die() if file doesn't exist
    * dpth       15       max depth to store when flushing to file
    * dflt                default value for data if no file
      goto                label in file to skip past before loading
      make                create file if necessary to store data (???)
    * poll      300       time (sec) to wait before checking to see if
                          file has been changed and requires reloading
  ----------------------------------------------------------------------
    * Flag is settable via $ENV{MMAgic_Data_$flag}

Parameters:

	$path	Pathname of data file.
	%init	Flags used in object creation

MMAgic::Data::path

(

)

Return the path of the file containing the underlying data.

MMAgic::Data::POP

(

)

MMAgic::Data::PUSH

(

)

MMAgic::Data::refresh

(

)

Cause underlying data to be refreshed.

MMAgic::Data::SHIFT

(

)

MMAgic::Data::SPLICE

(

)

MMAgic::Data::store

(

$

data

)

Store data into backing file.

Data is undefined in case of error. New data returned.

MMAgic::Data::STORE

(

)

MMAgic::Data::STORESIZE

(

)

MMAgic::Data::TIEARRAY

(

)

MMAgic::Data::TIESCALAR

(

)

MMAgic::Data::unlock

(

)

Release lock on tied object.

Returns without error if not locked.

MMAgic::Data::UNSHIFT

(

)

MMAgic::Data::UNTIE

(

)

MMAgic::Data::upToDate

(

)

Return true if the data is current.

---

The documentation for this class was generated from the following file:

• MMAgic/Data.pm