libdata-javascript-anon-perl 1.03-2 / usr / share / perl5 / Data / JavaScript / Anon.pm

package Data::JavaScript::Anon;

# This package provides a mechanism to convert the main basic Perl
# structures into JavaScript structures, making it easier to transfer
# data from Perl to JavaScript.

use 5.006;
use strict;
use warnings;
use Params::Util   qw{ _STRING _SCALAR0 _ARRAY0 _HASH0 };
use Class::Default ();

use vars qw{@ISA $VERSION $errstr $RE_NUMERIC $RE_NUMERIC_HASHKEY %KEYWORD};
BEGIN {
	$VERSION = '1.03';
	@ISA     = 'Class::Default';
	$errstr  = '';

	# Attempt to define a single, all encompasing,
	# regex for detecting a legal JavaScript number.
	# We do not support the exotic values, such as Infinite and NaN.
	my $_sci = qr/[eE](?:\+|\-)?\d+/;                   # The scientific notation exponent ( e.g. 'e+12' )
	my $_dec = qr/\.\d+/;                               # The decimal section ( e.g. '.0212' )
	my $_int = qr/(?:[1-9]\d*|0)/;                      # The integers section ( e.g. '2312' )
	my $real = qr/(?:$_int(?:$_dec)?|$_dec)(?:$_sci)?/; # Merge the integer, decimal and scientific parts
	my $_hex = qr/0[xX][0-9a-fA-F]+/;                   # Hexidecimal notation
	my $_oct = qr/0[0-7]+/;                             # Octal notation

	# The final combination of all posibilities for a straight number
	# The string to match must have no extra characters
	$RE_NUMERIC = qr/^(?:\+|\-)??(?:$real|$_hex|$_oct)\z/;

	# The numeric for of the hash key is similar, but without the + or - allowed
	$RE_NUMERIC_HASHKEY = qr/^(?:$real|$_hex|$_oct)\z/;

	%KEYWORD = map { $_ => 1 } qw{
		abstract boolean break byte case catch char class const
		continue debugger default delete do double else enum export
		extends false final finally float for function goto if
		implements import in instanceof int interface long native new
		null package private protected public return short static super
		switch synchronized this throw throws transient true try typeof
		var void volatile while with
	};
}





#####################################################################
# Top Level Dumping Methods

sub new {
	my $proto = shift;
	my $class = ref $proto || $proto;
	my $opts  = _HASH0($_[0]) ? shift : { @_ };

	# Create the object
	my $self = bless {
		quote_char => '"',
	}, $class;

	## change the default quote character
	if ( defined $opts->{quote_char} && length $opts->{quote_char} ) {
		$self->{quote_char} = $opts->{quote_char};
	}

	return $self;
}

sub _create_default_object {
	my $class = shift;
	my $self  = $class->new();
	return $self;
}

sub anon_dump {
	my $class     = shift;
	my $something = shift;
	my $processed = shift || {};

	# Handle the undefined case
	return 'undefined' unless defined $something;

	# Handle the basic non-reference case
	return $class->anon_scalar( $something ) unless ref $something;

	# Check to see if we have processed this reference before.
	# This should catch circular, cross-linked, or otherwise complex things
	# that we can't handle.
	if ( $processed->{$something} ) {
		return $class->_err_found_twice( $something );
	} else {
		$processed->{$something} = 1;
	}

	# Handle the SCALAR reference case, which in our case we treat
	# like a normal scalar.
	if ( _SCALAR0($something) ) {
		return $class->anon_scalar( $something );
	}

	# Handle the array case by generating an anonymous array
	if ( _ARRAY0($something) ) {
		# Create and return the array
		my $list = join ', ', map { $class->anon_dump($_, $processed) } @$something;
		return "[ $list ]";
	}

	# Handle the hash case by generating an anonymous object/hash
	if ( _HASH0($something) ) {
		# Create and return the anonymous hash
		my $pairs = join ', ', map {
			$class->anon_hash_key($_)
				. ': '
				. $class->anon_dump( $something->{$_}, $processed )
		} keys %$something;
		return "{ $pairs }";
	}

	$class->_err_not_supported( $something );
}

# Same thing, but creating a variable
sub var_dump {
	my $class = shift;
	my $name  = shift or return undef;
	my $value = $class->anon_dump( shift );
	"var $name = $value;";
}

# Wrap some JavaScript in a HTML script tag
sub script_wrap {
	"<script language=\"JavaScript\" type=\"text/JavaScript\">\n$_[1]\n</script>";
}

# Is a particular string a legal JavaScript number.
# Returns true if a legal JavaScript number.
# Returns false otherwise.
sub is_a_number {
	my $class  = shift;
	my $number = (defined $_[0] and ! ref $_[0]) ? shift : '';
	$number =~ m/$RE_NUMERIC/ ? 1 : '';
}





#####################################################################
# Basic Variable Creation Statements

# Create a JavaScript scalar given the javascript variable name
# and a reference to the scalar.
sub var_scalar {
	my $class      = shift;
	my $name       = shift or return undef;
	my $scalar_ref = _SCALAR0(shift) or return undef;
	my $value      = $class->js_value( $$scalar_ref ) or return undef;
	"var $name = $value;";
}

# Create a JavaScript array given the javascript array name
# and a reference to the array.
sub var_array {
	my $class     = shift;
	my $name      = shift or return undef;
	my $array_ref = _ARRAY0(shift) or return undef;
	my $list      = join ', ', map { $class->anon_dump($_) } @$array_ref;
	"var $name = new Array( $list );";
}

# Create a JavaScript hash ( which is just an object ), given
# the variable name, and a reference to a hash.
sub var_hash {
	my $class    = shift;
	my $name     = shift or return undef;
	my $hash_ref = _HASH0(shift) or return undef;
	my $struct   = $class->anon_hash( $name, $hash_ref ) or return undef;
	"var $name = $struct;";
}





#####################################################################
# Basic Serialisation And Escaping Methods

# Turn a single perl value into a single javascript value
sub anon_scalar {
	my $class = shift;
	my $value = _SCALAR0($_[0]) ? ${shift()} : shift;
	return 'null' unless defined $value;

	# Don't quote if it is numeric
	return $value if $value =~ /$RE_NUMERIC/;

	my $quote_char = $class->_self->{quote_char};

	# Escape and quote
	$quote_char . $class->_escape($value) . $quote_char;
}

# Turn a single perl value into a javascript hash key
sub anon_hash_key {
	my $class = shift;
	my $value = defined($_[0]) && !ref($_[0]) ? shift : return undef;

	my $quote_char = $class->_self->{quote_char};

	# Quote if it's a keyword
	return $quote_char . $value . $quote_char if $KEYWORD{$value};

	# Don't quote if it is just a set of word characters or numeric
	return $value if $value =~ /^[^\W\d]\w*\z/;
	return $value if $value =~ /$RE_NUMERIC_HASHKEY/;

	# Escape and quote
	$quote_char . $class->_escape($value) . $quote_char;
}

# Create a JavaScript array given the javascript array name
# and a reference to the array.
sub anon_array {
	my $class     = shift;
	my $name      = shift or return undef;
	my $array_ref = _ARRAY0(shift) or return undef;
	my $list      = join ', ', map { $class->anon_scalar($_) } @$array_ref;
	"[ $list ]";
}

# Create a JavaScript hash ( which is just an object ), given
# the variable name, and a reference to a hash.
sub anon_hash {
	my $class    = shift;
	my $name     = shift or return undef;
	my $hash_ref = _HASH0(shift) or return undef;
	my $pairs    = join ', ', map { 
		$class->anon_hash_key( $_ )
			. ': '
			. $class->anon_scalar( $hash_ref->{$_} )
	} keys %$hash_ref;
	"{ $pairs }";
}





#####################################################################
# Utility and Error Methods

sub _escape {
	my $class = shift;
	my $text  = shift;
	my $char  = $class->_self->{quote_char};
	$text =~ s/(\Q$char\E|\\)/\\$1/g;                       # Escape quotes and backslashes
	$text =~ s/\n/\\n/g;                                    # Escape newlines in a readable way
	$text =~ s/\r/\\r/g;                                    # Escape CRs in a readable way
	$text =~ s/\t/\\t/g;                                    # Escape tabs in a readable way
	$text =~ s/([\x00-\x1F])/sprintf("\\%03o", ord($1))/ge; # Escape other control chars as octal
	$text;
}

sub _err_found_twice {
	my $class     = shift;
	my $something = ref $_[0] || 'a reference';
	$errstr = "Found $something in your dump more than once. "
		. "Data::JavaScript::Anon does not support complex, "
		. "circular, or cross-linked data structures";
	undef;
}

sub _err_not_supported {
	my $class     = shift;
	my $something = ref $_[0] || 'A reference of unknown type';
	$errstr = "$something was found in the dump struct. "
		. "Data::JavaScript::Anon only supports objects based on, "
		. "or references to SCALAR, ARRAY and HASH type variables.";
	undef;
}

1;

__END__

=pod

=head1 NAME

Data::JavaScript::Anon - Dump big dumb Perl structs to anonymous JavaScript structs

=head1 SYNOPSIS

  # Dump an arbitrary structure to javascript
  Data::JavaScript::Anon->anon_dump( [ 'a', 'b', { a => 1, b => 2 } ] );

=head1 DESCRIPTION

Data::JavaScript::Anon provides the ability to dump large simple data
structures to JavaScript. That is, things that don't need to be a class,
or have special methods or whatever.

The method it uses is to write anonymous variables, in the same way you
would in Perl. The following shows some examples.

  # Perl anonymous array
  [ 1, 'a', 'Foo Bar' ]
  
  # JavaScript equivalent ( yes, it's exactly the same )
  [ 1, 'a', 'Foo Bar' ]
  
  # Perl anonymous hash
  { foo => 1, bar => 'bar' }
  
  # JavaScript equivalent
  { foo: 1, bar: 'bar' }

One advantage of doing it in this method is that you do not have to
co-ordinate variable names between your HTML templates and Perl. You
could use a simple Template Toolkit phrase like the following to get
data into your HTML templates.

  var javascript_data = [% data %];

In this way, it doesn't matter WHAT the HTML template calls a
particular variables, the data dumps just the same. This could help
you keep the work of JavaScript and Perl programmers ( assuming you
were using different people ) seperate, without creating 
cross-dependencies between their code, such as variable names.

The variables you dump can also be of arbitrary depth and complexity,
with a few limitations.

=over 4

=item ARRAY and HASH only

Since arrays and hashs are all that is supported by JavaScript, they
are the only things you can use in your structs. Any references or a
different underlying type will be detected and an error returned.

Note that Data::JavaScript::Anon will use the UNDERLYING type of the
data. This means that the blessed classes or objects will be ignored
and their data based on the object's underlying implementation type.

This can be a positive thing, as you can put objects for which you expect
a certain dump structure into the data to dump, and it will convert to 
unblessed, more stupid, JavaScript objects cleanly.

=item No Circular References

Since circular references can't be defined in a single anonymous struct,
they are not allowed. Try something like L<Data::JavaScript> instead.
Although not supported, they will be detected, and an error returned.

=back

=head1 MAIN METHODS

All methods are called as methods directly, in the form
C<< Data::JavaScript::Anon->anon_dump( [ 'etc' ] ) >>.

=head2 anon_dump STRUCT

The main method of the class, anon_dump takes a single arbitrary data
struct, and converts it into an anonymous JavaScript struct.

If needed, the argument can even be a normal text string, although it
wouldn't do a lot to it. :)

Returns a string containing the JavaScript struct on success, or C<undef>
if an error is found.

=head2 var_dump $name, STRUCT

As above, but the C<var_dump> method allows you to specify a variable name,
with the resulting JavaScript being C<var name = struct;>. Note that the
method WILL put the trailing semi-colon on the string.

=head2 script_wrap $javascript

The C<script_wrap> method is a quick way of wrapping a normal JavaScript html
tag around your JavaScript.

=head2 is_a_number $scalar

When generating the javascript, numbers will be printed directly and not
quoted. The C<is_a_number> method provides convenient access to the test
that is used to see if something is a number. The test handles just about
everything legal in JavaScript, with the one exception of the exotics, such
as Infinite, -Infinit and NaN.

Returns true is a scalar is numeric, or false otherwise.

You may also access method in using an instantiated object.

=head2 new HASH

This will create a Data::JavaScript::Anon object that will allow you to change
some of the default behaviors of some methods.

    Options:
        quote_char  : Set the quote_char for stirng scalars. Default is '"'.

=head1 SECONDARY METHODS

The following are a little less general, but may be of some use.

=head2 var_scalar $name, \$scalar

Creates a named variable from a scalar reference.

=head2 var_array $name, \@array

Creates a named variable from an array reference.

=head2 var_hash $name, \%hash

Creates a named variable from a hash reference.

=head2 anon_scalar \$scalar

Creates an anonymous JavaScript value from a scalar reference.

=head2 anon_array \@array

Creates an anonymous JavaScript array from an array reference.

=head2 anon_hash \%hash

Creates an anonymous JavaScript object from a hash reference.

=head2 anon_hash_key $value

Applys the formatting for a key in a JavaScript object

=head1 SUPPORT

Bugs should be reported via the CPAN bug tracker at:

L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-JavaScript-Anon>

For other comments or queries, contact the author.

=head1 AUTHOR

Adam Kennedy E<lt>adamk@cpan.orgE<gt>

=head1 SEE ALSO

L<JSON>, L<http://ali.as/>

=head1 COPYRIGHT

Copyright 2003 - 2009 Adam Kennedy.

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

The full text of the license can be found in the
LICENSE file included with this module.

=cut