bar() and $foo->element('bar')->get()?
XML::Comma FAQ - frequently asked questions about XML::Comma
XML::Comma is an information management platform. It was designed to be used as a core tool for developing Very Large Websites. Comma specifies an XML-based document definition format, encourages Perl code to be embedded in these definitions, and specifies an API for manipulating documents and document collections. Comma includes functionality to store sets of documents in ordered, extensible ways, and integrates with a relational database to index, sort and retrieve collections of documents.
XML::Comma is Free Software released under the GNU General Public License. For more information about the license, please see http://www.fsf.org/licenses/gpl.html
Comma is distributed as a Perl module. The most recent version is always available at http://xml-comma.org/download/
Yes. Please see http://xml-comma.org/mailing-list.html
The XML::Comma User's Guide describes the Comma API in detail. It
is available in HTML and PDF. The Guide can be found in the Comma/docs
directory of the distribution, or at:
http://xml-comma.org/guide-filter.html http://xml-comma.org/guide.pdf
bar() and $foo->element('bar')->get()?This is really a question about Comma's ``shortcut'' syntax, which defines a mapping between method calls and the elements of a given container.
There is a section on the shortcut syntax in the guide that goes into more detail, but here is a quick list of the seven possible ways a shortcut can can be resolved.
$x->foo ( [@args] ) # becomes:
$x->method('foo, @args) # if there is a method "foo"
$x->element('foo') # singular, nested
$x->elements('foo') # plural, nested
$x->element('foo')->get() # singular, non-nested, no @args
$x->element('foo')->set(@args) # singular, non-nested, with @args
$x->elements_group_get('foo') # plural, nested, no @args
$x->elements_group_set('foo', @args) # plural, nested, with @args
Because the elements() method always tries to return a ``list'' of
elements -- which means that it returns an array in list context and a
reference to an array in scalar context -- you have to do a bit of
extra work to determine how many instances of a plural element
exist. The most concise (and the recommended) way to do this is:
my $how_many_foos = scalar ( @{$doc->elements('foo')} );
You have a problem that boils down to something along these lines:
$doc->element('some_element')->set ( "foo & bar" );
Element content must be legal XML -- so no <, >, or &
characters are allowed. These special characters must be ``escaped'' by
replacing them with their entity codes (respectively &lt;,
&gt;, or &amp;). The Comma::Util::XML_basic_escape() and
Comma::Util::XML_basic_unescape() methods are available, as are
shortcut flags for the element set() and get() methods:
$doc->element('some_element()->set ( "foo & bar", escape=>1 );
$doc->element('some_element')->get ( unescape=>1 );
$doc->some_element ( "foo & bar", escape=>1 );
Note that there is no way to pass the unescape flag in the
shortcut-get syntax (so there are three examples above, rather than
four). It is fair to construe this as a problem with the API.
Comma writes a line about all un-caught errors to a log file. The
location of the log file is controlled by a setting in Comma.pm -- the
default is /tmp/log.comma/. This file probably needs to be writable
by any processes that use the Comma framework. In most installations,
the file is made world-writable (which should tell you that the Comma
log system isn't intended to be used as part of any security auditing
or similar framework -- you should write additional code to handle any
secure reporting that an application might need.)
Sure. We don't know of any faster way to develop (or to add new features to) large-scale applications that manipulate collections of hundreds of thousands of pieces of messy-but-structured information. We use it every day, and so do many, many people who access the web sites we build.
Oh, wait: you meant, ``does it run fast?'' Well, that's in the eye of the beholder. Comma's bottleneck is the parsing and object-ifying of XML files. The power and flexibility that the API gives you comes at some cost -- a hand-coded, special-purpose implementation could well be faster for any single usage.
However, we've worked hard to make Comma fast enough to be really, really, useful. For example, Comma's ``Inline'' parser is about twice as fast as the general-use XML parsers against which we've benchmarked it (because Comma documents aren't allowed to make use of all parts of the XML specification). An experienced designer of large-scale internet systems will easily be able to structure and tune a Comma-based system to serve hundreds of thousands of dynamic pages a day on mid-range x86 boxes.