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

BUGS
TODO
SEE ALSO
AUTHOR
COPYRIGHT

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:

From a parser
One object class this module gives you, XML::ComicsML::Parser, subclasses XML::Parser, so you may use all of that module's object methods with this one, including the methods that parse existing files, filehandles or scalars. The return value of all parsing methods is an object belonging to the XML::ComicsML::Comic class.
The parser performs several checks specific to ComicsML validity as it traverses a document, and will croak if it finds any errors.
Roll your own
Alternatively, you may simply construct your own XML::ComicsML::Comic object, and use its methods to fill in all its information. More complex contents, such as strips, will need separate construction and then insertion into the Comic object through the approproate method (the new_strip method, in a Strip object's case).

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

Need methods for removing objects from their parents. (Yanking panels from strips, for example, or lines from panel-descs.)
Get rid of that silly and error-prone AUTOLOAD nonsense.
Let the various sub-objects all have their own as_string methods.