PageArchive is a perl5 package that implements a set of methods for maintaining a versioned set of pages as files within a directory. It was created to replace a similar DBM tied-hash implementation used by WebWeb, and is particularly useful on machines which don't have a DBM which can handle entries more than 1K long. It uses a utility package, Storable (also documented here), to transform page objects into scalars suitable for storage and retrieval by PageArchive.

Source is available under an open source license from prtims.stx.com, along with WebWebTwo.

----
'''PageArchive'''
	* Handles saving multiple versions of page objects
	* No dependence on any underlying DBM implementation
	* Easy-to-maintain page files
	* Log file support

'''Global Variables'''
	* $PageArchive::DEBUG
		* Set this variable to a non-zero value to enable debugging.
		* Causes the PageArchive package to log debugging information to the log file (q.v.)

'''Class Methods'''
	* new(dirname)
		* Creates a new PageArchive object.
		* Verifies that the supplied directory can be opened; creates it if it does not exist

'''Instance Methods'''
	* defined(name[,version])
		* Determines if a given page and version exists
		* If no version is supplied, returns list of all versions that match the name

	* max_version(name)
		* Returns the maximum version number associated with the name, or undef if there is none

	* get(name,version)
		* Restore the page object corresponding to this name and version
		* Returns undef if it does not exist

	* put(name,contentsref[,version])
		* Store the page object pointed to by contentsref
		* If version is not supplied, assume version 1.

	* delete(name[,version])
		* Delete file corresponding to this page
		* Assume most recent version if none supplied

	* purge(name)
		* Remove all versions of this page

	* iterator()
		* Returns a list of all highest-number versions of all pages

	* setError(msg1,msg2, ..., msgN)
		* Set the message to be retrieved by getError()

	* getError()
		* Returns last error set by setError()

	* setLog(logname)
		* Sets up the log to be written to by the log() method

	* log(msg1, msg2, ..., msgN)
		* Logs a message to the current log file.
----
'''Storable'''

A pretty good way to "flatten" most objects into scalars, for ultimate storage into a DBM-like database. The following objects may be flattened:
	* The undefined value.
	* Simple scalars.
	* Reference to unblessed arrays, whose elements are themselves storable objects.
	* References (blessed or unblessed) to hashes, whose keys are printable scalars, and whose instance variables are themselves storable objects.

You can use it in a non-OO way...

	# Flatten an object:
	my $fluffy = ['nice', 'and', 'fluffy'];
	my $flat = IU::Storable->flatten($fluffy);

	# Inflate it again (note that we pass in a reference for efficiency):
	my $fluffy = IU::Storable->inflate(\$flat);
Or you can inherit from it...

	package Stuff;
	@ISA = qw(IU::Storable);
	...
	my $flat = $fluffy->flatten;
	my $fluffy = Stuff->inflate(\$flat);
'''Public interface'''
	* flatten(objectref)
		* As instance method: turn the "self" object into a scalar.
		* As class method: turn 'objectref' argument into a scalar.

	* inflate(scalarref)
		* As class method: turn 'scalarref' back into an object.
-- JoeMcMahon

----
Very useful stuff, thanks Joe. Check out CvWiki for a different approach to the same problem. -- PeterMerel