/ 
Data-JavaScript-LiteObject-1.01
River stage zero No dependents
/ Data::JavaScript::LiteObject

NAME

Data::JavaScript::LiteObject - Perl package to provide lightweight data dumping

SYNOPSIS

use Data::JavaScript:LiteObject;

jsodump("user", \%users);

DESCRIPTION

This module was inspired by Data::JavaScript, which while incredibly versatile, seems rather brute force and inelegant for certain forms of data. Specifically a series of objects of the same class, which it seems is a likely use for this kind of feature. So this module was created to provide a lightweight means of producing configurable, clean and compact output.

LiteObject is used to format and output an array or hash of objects; that is hash references. The referenced hashes may contain values that are scalars, or references to arrays containing scalars.

LiteObject contains one function; jsodump; which takes a list of named parameters. Two of which are required, the rest being optional.

Required parameters

protoName

The name to be used for the prototype object function.

dataRef

A reference to an array or hash of hashes to dump.

Optional parameters

attributes

A reference to an array containing a list of the object attributes (hash keys). This is useful if every object does not necessarily posses a value for each attributes; exists fails. e.g.

%A = (a=>1, z=>26);
%B = (b=>2, y=>25);

jsodump("example", \(%A, %B), \('a', 'b', 'y', 'z'));

This could also be used to explicitly prevent certain data from being dumped.

explode

The default; false; produces output with one object per line. If true, the output is one attribute per line.

lineIN

If true, output is numbered every 5 lines. The value provided should be the number of lines printed before this output. For example if a CGI script included:

    C<print q(<html>
	    <head>
	    <title>Pthbb!!</title>
	    <script language=javascript>);>
    jsdump(protoName=>"object", dataRef=>\@objects, lineIN=>4);

The client might see:

<html>
<head>
<title>Pthbb!!</title>
<script language=javascript>
// 5
function object (x, y, z) {
        this.x = x; this.y = y; this.z = z; }
object0 = new object(1, 0, 0 );
object1 = new object(0, 1, 0 );
// 10
object2 = new object(0, 0, 1 );

making it easier to read and/or debug.

lineOUT

A scalar reference. jsodump will set it's value to the number of the last line of numbered output produced when lineIN is specified. This way you may pass the scalar to a subsequent call to jsdump as the value of lineIn for continuous numbering. For example:

C<jsdump(protoName=>"object", dataRef=>\@objects, lineIN=>4, lineOUT=>\$.);>

...

C<jsdump(protoName=>"object", dataRef=>\@objects, lineIN=>$.);>
listObjects

If true, the parameters value is used as the name of an array to be output contaning a list of all the objects dumped. This way, your client side code need not know as much about the data, but simply to traverse an array of your choosing.

For example:

C<jsdump(protoName=>"object", dataRef=>\@objects, listObjects=>"objects");>

would return

objects = new Array('object0', 'object1', 'object2');

CAVEATS

All of the objects in a given hash or array reference should contain the same keys. Explicit undefined values should be used for instances of an object that do not posess a certain value. For example:

C<%hash0 = (alpha=>undef, beta=>1);>
C<%hash1 = (beta=>1);>

%hash0 is safe, since exists($hash0{alpha}) is true. However exists($hash1{alpha}) is false, and %hash1 would cause problems.

Deep structures are not dumped. That is anything beyond a scalar or a scalar within an Array as an attribute value. It is not entirely clear that it's necessary, but if you require it "SEE ALSO"

BUGS

Nothing that am I aware of.

SEE ALSO

Data::JavaScript

AUTHOR

Jerrad Pierce belg4mit@mit.edu, webmaster@pthbb.org. http://pthbb.org/