/ 
DDC-XS-0.27
River stage zero No dependents
/ DDC::XS::Object

NAME

DDC::XS::Object - common perl base class for DDC::XS objects

SYNOPSIS

#-- Preliminaries
use DDC::XS;
$CLASS = 'DDC::XS::Object';

##---------------------------------------------------------------------
## C -> Perl
$q    = DDC::XS->parse("foo && bar");
$qs   = $q->toString;                  ##-- $qs is "('foo' && 'bar')"
$hash = $q->toHash();                  ##-- query encoded as perl hash-ref

#... the perl object can be manipulated directly (perl refcounting applies)
$hash->{Dtr1} = {class=>'CQTokExact',Value=>'baz'};    ##-- NO memory leak!

##---------------------------------------------------------------------
## Perl->C
$q2   = $CLASS->newFromHash($hash);    ##-- $q2 needs explicit free()
$qs2  = $q2->toString();               ##-- $qs2 is "(@'baz' && 'bar')

##---------------------------------------------------------------------
## Deep copy & Traversal

$q3 = $q->clone();                     ##-- wraps newFromHash($q->toHash)
$q  = $q->mapTraverse(\&CODE);         ##-- recursively tweak sub-objects

##---------------------------------------------------------------------
## JSON utilities
$json = $q->toJson();                  ##-- ddc-internal json-ification
$json = $q->TO_JSON();                 ##-- wraps toHash() for the JSON module
$obj  = $CLASS->newFromJson($str);     ##-- wraps newFromHash(from_json($str))

##---------------------------------------------------------------------
## Debugging
$obj->DumpTree();                      ##-- dumps substructure to STDERR
$obj->free();                          ##-- expplicit deep destruction, use at your own risk
\@kids = $obj->Children();             ##-- ARRAY-ref of direct children
\@desc = $obj->Descendants();          ##-- ARRAY-ref of descendants
undef  = $obj->DisownChildren();       ##-- prevent deep destruction (you should never need this)
$cnt   = $obj->refcnt();               ##-- get internal reference count (NOT the same as perl's)

DESCRIPTION

The DDC::XS::Object class provides convenience methods for mapping back and forth between "opaque" pointer-based objects in the DDC::XS:: hierarchy and perl-side representations of these encoded as HASH-refs. The methods defined by this class are intended as convenience wrappers for dealing with complex nested object structures using transparent perl hashes with perl reference-counting for memory management, rather than DDC::XS reference counting.

DDC::XS::Object objects and their descendants use an internal reference counting strategy in addition to perl's reference counts in order to determine when objects can be safely destroyed. This strategy attempts to ensure that all DDC::XS::Objects are destroyed when the last reference is dropped, where both perl references and C++-level embedded object pointers constitute "references" in this sense. If you so desire, you can force (deep) object destruction by calling the DDC::XS::Object free() method, although this is currently not recommended for general use.

SEE ALSO

perl(1), DDC::XS(3perl), DDC::XS::CQuery(3perl), DDC::XS::CQCount(3perl), DDC::XS::CQFilter(3perl), DDC::XS::CQueryOptions(3perl), DDC::XS::CQueryCompiler(3perl).

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Bryan Jurish

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.