Podcasts

The Gameshelf

Jmac's Arcade

Nerdy Books

with me in them

Mac OS X in a Nutshell Perl & XML Mac OS X Hacks
XML::ComicsML - create, write, and parse ComicsML files

NAME

XML::ComicsML - create, write, and parse ComicsML files

SYNOPSIS

 use XML::ComicsML;


 # parse an existing ComicsML file
 my $parser = XML::ComicsML::Parser->new;
 my $comic = $parser->parsefile('my_comic.xml');

 my $title = $comic->title;
 print "The title of this comic is $title\n";
 my @strips = $comic->strips;
 print "It has ".scalar(@strips)." strips associated with it.\n";
 # build a comic object out of thin air, instead of parsing
 my $comic2 = XML::ComicsML::Comic->new;
 $comic2->title('Perl Adventures');
 $comic2->url('http://www.jmac.org/perlcomix/index.html');
 # define a person for it
 my $me = $comic2->new_person;
 $me->firstname('Emma');
 $me->surname('Shrimphaven');
 $me->email('emmashr@jmac.org');
 # add a strip
 my $strip1 = $comic2->new_strip('PA-1'); # My arbitrary ID for this strip
 $strip1->url('http://www.jmac.org/perlcomix/pa-1.html');
 $strip1->description('Captain Perl learns about list context.');


 # I could add some panel description here, but I am too lazy.
 # Let's just print out what we have to STDOUT.
 $comic2->as_string;

DESCRIPTION

This module provides a programmer interface for creating, parsing, and otherwise working with documents written according to the ComicsML format for describing digital comics, much as XML::RSS does for the RSS syndication format.

The main object class that this module defines is XML::ComicsML::Comic, which represents an entire document, and holds various fields and other objects representing the document's content. There are two main ways to create this object:

Of course, you can combine these strategies, parsing an existing file to create a Comic object with some content in it and then manipulating, adding to, and subtracting from that content however you like through the methods available through that object and all its content objects.

METHODS

XML::ComicsML::Parser Methods

new
Class method. Creates a new parser object.

parse
parsefile
...and so on
XML::ComicsML objects inherit from XML::Parser, so all the lovely XML-parsing methods those objects give you also exist here. See the XML::Parser manpage for more information on using them.

XML::ComicsML::Comic Methods

From this point on, we'll use a lot of terms specific to ComicsML, such as the particular things 'comic' and 'strip' mean in its context, so we'll assume you're already familiar with them. If not, please refer to the general ComicsML documentation, a URL to which you can find in the SEE ALSO section of this manpage.

new
Class method. Creates a new Comic object.

new_strip
Creates a new XML::ComicsML::Strip object, adds it to the comic's list of panels, and returns it to you. Under most circumstances, this should be your Strip object constructor of choice.

strips
Returns a list of all Strip objects attached to this Comic.

new_person
Creates an XML::ComicsML::Person object as a child of this Comic, and returns it to you.

people
Returns a list of all Person objects attached to this Strip.

people
Returns a list of all Person object attached to this Comic.

version
language
title
last_built
icon
description
These methods are simple accessors: they each return the current value of some field on the object, and if called with a single argument, set it to that value first. Each relates to an attribute or sub-element of the <comic> element within a ComicsML document. See the documentation for ComicsML itself for more details about what sorts of content they should contain.

Note about language: An object's language attribute corresponds to the special ``xml:lang'' XML attribute, and ComicsML treats this as a lexically scoped value. Therefore, if you set a value through the language accessor of any object in the XML::ComicsML hiearchy, then all the objects it contains will be able to read the same langauge value through the language accessor -- unless, of course, one of these objects sets its own langauge value, which will in turn get passed on to its own contents.

None of the other simple accessors anywhere else in the ComicsML object tree are this wacky; they get or set values only as they might appear on that one object, with no mind given to parents or children. So there you have it.

as_string
Turns the Comic object into XML, courtesy of the XML::Writer module. Uh, I did mention you need XML::Writer, right?

Passes along any arguments it recives as a hash to the underlying constructor call to XML::Writer, so you can feed this method, for example, a filehandle reference keyed under 'OUTPUT', and have the ComicsML document wind up there.

By default, it prints to STDOUT, and uses a two-space indentation style.

XML::ComicsML::Strip Methods

new_panel
Creates a new XML::ComicsML::Panel object, adds it to the end of the comic's list of panels, and returns it to you. Under most circumstances, this should be your Panel object constructor of choice.

The order in which a Strip object keeps its Panel objects is the same as the order in which a human reader should encounter them -- in other words, the order in which they would appear in an actual ComicsML document.

new_teaser_panel
Just like new_panel, except that the panel it returns will appear inside the strip's teaser section, instead of its panels proper.

panels
Returns a list of all panel objects that live inside the main panels section of this strip, in order of appearance.

teaser_panels
Returns a list of all panel objects that live inside the teaser panels section of this strip, in order of appearance.

new_person
Creates an XML::ComicsML::Person object as a child of this Strip, and returns it to you.

people
Returns a list of all Person objects attached to this Strip.

title
url
date
description
Simple accessors that return the current value of the proper flavor of strip attribute. Call with an argument to set it as such.

Note: description sets the description that will appear in the strip's teaser section.

XML::ComicsML::Panel Methods

new_desc
Creates a new XML::ComicsML::Panel::Desc object, adds it to the comic's list of panels, and returns it to you. Under most circumstances, this should be your Panel::Desc object constructor of choice.

If called with an argument, it understands it as a language code, and files this new panel-desc object under that language. If called with no arguments, then the panel will file this desc under the same language code as the one the panel had set as its own language.

panel_descs
If called in list context, returns a hash of all Panel::Desc objects associated with this panel, keyed under their language codes. One of them, the default desc, will show up twice, under the key 'default'. This is normal and beautiful.

If called in scalar context, returns only the default desc.

get_panel_desc
If called with a string argument, understands it as a language code, and returns the Panel::Desc object filed in this panel under that language.

If called with no arguments, returns the default Panel::Desc object.

caption
url
Simple accessors that return the current value of the proper flavor of strip attribute. Call with an argument to set it as such.

XML::ComicsML::Panel::Desc Methods

new_line
Creates a new XML::ComicsML::Panel::Desc::Line object, adds it to the panel-desc's list of lines, and returns it to you. Under most circumstances, this should be your Panel::Desc::Line object constructor of choice.

new_thought
new_speech
new_action
new_narration
Convenience methods that work just like new_line, but also set the new Panel::Desc::Line object's type for you.

XML::ComicsML::Panel::Desc::Line Methods

Objects of this class hold the actual text of panel descriptions.

type
Sets the type of this line; either speech, thought, narration or action.

add_text
Called with one argument, adds it as unstyled text to this line -- it's ``normal'' text that won't receive any special markup as XML.

Called with two arguments, adds the first as text with the second argument understood as a style to apply to it -- in effect, adding an XML inline element to this line.

For example:

 $line->add_text('Foo');

...will simply add 'Foo' as plain text to the current line. And:

 $line->add_text('Bar', 'emphasis');

...will ``Bar'' with an ``emphasis'' style to the current line. If you were to print this line as XML at this point, it would look like this:

 Foo<emphasis>Bar</emphasis>

text
Returns a list of anonymous two-element arrays holding all this line's text and styles. If called on the line we've been building so far, we'd get this: 
 ( ['Foo', 'normal'],
   ['Bar', 'emphasis'] )

Note how unstyled text actually gets 'normal' as a default style.

plaintext
Returns a single string holding all text in this line, with its style removed. If called on our exmaple line object we'd get: 
 Foo Bar

Note that it automatically inserts a space in between text segments (unless they had space already between them).

add_character
Only applicable with Desc objects of 'speech' or 'thought' type. Takes a string argument, and adds a character with that name to the list of characters speaking or thinking the current line.

characters
Returns a list of all characters (themselves represented by simple scalars) speaking or thinking the current line.

target
For 'speech'-type lines, fetches the current value of its 'target' attribute. If called with a string argument, sets it to that first.

XML::ComicsML::Person Methods

firstname
surname
email
url
job
Simple accessors that return the current value of the proper flavor of strip attribute. Call with an argument to set it as such.

BUGS

Probably lots. Don't hesitate to email me if you find any, or see sorely lacking features.

TODO

SEE ALSO

The ComicsML resource page: http://www.jmac.org/projects/comics_ml/

the XML::Parser manpage

the XML::Writer manpage

AUTHOR

Jason McIntosh <jmac@jmac.org>

COPYRIGHT

Copyright (c) 2001 by Jason McIntosh <jmac@jmac.org>.

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