Debian Codegraph @

README

raw
1 NAME
2 XML::Atom::Microformats - parse microformats in Atom content
3
4 SYNOPSIS
5 use XML::Atom::Microformats;
6
7 my $feed = XML::Atom::Microformats
8 -> new_feed( $xml, $base_uri )
9 -> assume_profile( qw(hCard hCalendar) );
10 print $feed->json(pretty => 1);
11
12 my $results = RDF::Query
13 -> new( $sparql )
14 -> execute( $feed->model );
15
16 DESCRIPTION
17 The XML::Atom::Microformats module brings the functionality of
18 HTML::Microformats to Atom 1.0 Syndication feeds. It finds microformats
19 embedded in the <content> elements (note: not <summary>) of Atom
20 entries.
21
22 The general pattern of usage is to create an XML::Atom::Microformats
23 object (which corresponds to an Atom 1.0 feed) using the "new_feed"
24 method; tell it which types of Microformat you expect to find there;
25 then ask for the data, as a Perl hashref, a JSON string, or an
26 RDF::Trine model.
27
28 Constructor
29 "XML::Atom::Microformats->new_feed($xml, $base_url)"
30 Constructs a feed object.
31
32 $xml is the Atom source (string) or an XML::LibXML::Document.
33
34 $base_url is the feed URL, important for resolving relative URL
35 references.
36
37 Profile Management Methods
38 HTML::Microformats uses HTML profiles (i.e. the profile attribute on the
39 HTML <head> element) to detect which Microformats are used on a page.
40 Any microformats which do not have a profile URI declared will not be
41 parsed.
42
43 XML::Atom::Microformats uses a similar mechanism. Because Atom does not
44 have a <head> element, Atom <link> is used instead:
45
46 <link rel="profile" href="http://ufs.cc/x/hcalendar" />
47
48 These links can be used on a per-entry basis, or for the whole feed.
49
50 Because many feeds fail to properly declare which profiles they use,
51 there are various profile management methods to tell
52 XML::Atom::Microformats to assume the presence of particular profile
53 URIs, even if they're actually missing.
54
55 "add_profile(@profiles)"
56 Using "add_profile" you can add one or more profile URIs, and they
57 are treated as if they were found on the document.
58
59 For example:
60
61 $feed->add_profile('http://microformats.org/profile/rel-tag')
62
63 This is useful for adding profile URIs declared outside the document
64 itself (e.g. in HTTP headers).
65
66 "entry_add_profile($entryid, @profiles)"
67 "entry_add_profile" is a variant to allow you to add a profile which
68 applies only to one specific entry within the feed, if you know that
69 entry's ID.
70
71 "assume_profile(@microformats)"
72 For example:
73
74 $feed->assume_profile(qw(hCard adr geo))
75
76 This method acts similarly to "add_profile" but allows you to use
77 names of microformats rather than URIs. Microformat names are case
78 sensitive, and must match HTML::Microformats::Format::Foo module
79 names.
80
81 "entry_assume_profile($entryid, @profiles)"
82 "entry_assume_profile" is a variant to allow you to add a profile
83 which applies only to one specific entry within the feed, if you
84 know that entry's ID.
85
86 "assume_all_profiles"
87 This method is equivalent to calling "assume_profile" for all known
88 microformats.
89
90 "entry_assume_all_profiles($entryid)"
91 This method is equivalent to calling "entry_assume_profile" for all
92 known microformats.
93
94 Parsing Methods
95 You can probably skip this section. The "data", "json" and "model"
96 methods will automatically do this for you.
97
98 "parse_microformats"
99 Scans through the feed, finding microformat objects.
100
101 On subsequent calls, does nothing (as everything is already parsed).
102
103 "clear_microformats"
104 Forgets information gleaned by "parse_microformats" and thus allows
105 "parse_microformats" to be run again. This is useful if you've added
106 some profiles between runs of "parse_microformats".
107
108 Data Retrieval Methods
109 These methods allow you to retrieve the feed's data, and do things with
110 it.
111
112 "objects($format)"
113 $format is, for example, 'hCard', 'adr' or 'RelTag'.
114
115 Returns a list of objects of that type. (If called in scalar
116 context, returns an arrayref.)
117
118 Each object is, for example, an HTML::Microformat::hCard object, or
119 an HTML::Microformat::RelTag object, etc. See the relevent
120 documentation for details.
121
122 "entry_objects($entryid, $format)"
123 "entry_objects" is a variant to allow you to fetch data for one
124 specific entry within the feed, if you know that entry's ID.
125
126 "all_objects"
127 Returns a hashref of data. Each hashref key is the name of a
128 microformat (e.g. 'hCard', 'RelTag', etc), and the values are
129 arrayrefs of objects.
130
131 Each object is, for example, an HTML::Microformat::hCard object, or
132 an HTML::Microformat::RelTag object, etc. See the relevent
133 documentation for details.
134
135 "entry_all_objects($entryid)"
136 "entry_all_objects" is a variant to allow you to fetch data for one
137 specific entry within the feed, if you know that entry's ID.
138
139 "json(%opts)"
140 Returns data roughly equivalent to the "all_objects" method, but as
141 a JSON string.
142
143 %opts is a hash of options, suitable for passing to the JSON
144 module's to_json function. The 'convert_blessed' and 'utf8' options
145 are enabled by default, but can be disabled by explicitly setting
146 them to 0, e.g.
147
148 print $feed->json( pretty=>1, canonical=>1, utf8=>0 );
149
150 "entry_json($entryid, %opts)"
151 "entry_json" is a variant to allow you to fetch data for one
152 specific entry within the feed, if you know that entry's ID.
153
154 "model(%opts)"
155 Returns data as an RDF::Trine::Model, suitable for serialising as
156 RDF or running SPARQL queries. Quads are used (rather than triples)
157 which allows you to trace statements to the entries from which they
158 came.
159
160 $opts{'atomowl'} is a boolean indicating whether or not to include
161 data from XML::Atom::OWL in the returned model. If enabled, this
162 always includes AtomOWL data for the whole feed (not just for a
163 specific entry), even if you use the "entry_model" method.
164
165 If RDF::RDFa::Parser 1.096 or above is installed, then
166 $opts{'atomowl'} will automatically pull in DataRSS data too.
167
168 "entry_model($entryid, %opts)"
169 "entry_model" is a variant to allow you to fetch data for one
170 specific entry within the feed, if you know that entry's ID.
171
172 "add_to_model($model, %opts)"
173 Adds data to an existing RDF::Trine::Model. Otherwise, the same as
174 "model".
175
176 "entry_add_to_model($entry, $model, %opts)"
177 Adds data to an existing RDF::Trine::Model. Otherwise, the same as
178 "entry_model".
179
180 BUGS
181 Please report any bugs to <http://rt.cpan.org/>.
182
183 SEE ALSO
184 HTML::Microformats, XML::Atom::OWL, XML::Atom::FromOWL,
185 RDF::RDFa::Parser.
186
187 <http://microformats.org/>, <http://www.perlrdf.org/>.
188
189 AUTHOR
190 Toby Inkster <[email protected]>.
191
192 COPYRIGHT
193 Copyright 2010-2012 Toby Inkster
194
195 This library is free software; you can redistribute it and/or modify it
196 under the same terms as Perl itself.
197
198 DISCLAIMER OF WARRANTIES
199 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
200 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
201 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
202