File Coverage

blib/lib/Web/Microformats2.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package Web::Microformats2;
2              
3 2     2   2460 use Web::Microformats2::Parser;
  2         8  
  2         78  
4 2     2   20 use Web::Microformats2::Document;
  2         5  
  2         152  
5              
6             our $VERSION = '0.511';
7              
8             1;
9              
10             =pod
11              
12             =head1 NAME
13              
14             Web::Microformats2 - Read Microformats2 metadata from HTML or JSON
15              
16             =head1 SYNOPSIS
17              
18             use Web::Microformats2;
19             use v5.10;
20              
21             my $mf2_parser = Web::Microformats2::Parser->new;
22             my $mf2_doc = $mf2_parser->parse( $string_full_of_tasty_html );
23              
24             for my $item ( $mf2_doc->all_top_level_items ) {
25             # Each $item is a Web::Microformats2::Item object.
26             my @types = $item->all_types;
27             say "I see an MF2 item with these types set: @types";
28              
29             my $name = $item->get_property( 'name' );
30             say "The value of the item's 'name' property is: '$name'";
31             }
32              
33             my $serialized_mf2_doc = $mf2_doc->as_json;
34              
35             my $other_mf2_doc = Web::Microformats2::Document->new_from_json(
36             $serialized_mf2_doc_from_somewhere_else
37             );
38              
39             =head1 DESCRIPTION
40              
41             The Web::Microformats2 modules provide Perl programs with a way to parse
42             and analyze HTML documents containing Microformats2 metadata. They can
43             pull Microformats2 information from a given HTML document, representing
44             it as a queryable in-memory object. They can also serialize this object
45             as JSON (using the Microformats2 rules for this), or read an already
46             JSON-serialized Microformats2 structure for further analysis.
47              
48             See L<"ABOUT MICROFORMATS2">, below, for arguments about why this might
49             be interesting to you.
50              
51             =head1 CLASSES
52              
53             =over
54              
55             =item L<Web::Microformats2::Parser>
56              
57             Parses HTML for Microformats2 metadata. Returns what it finds as a
58             Web::Microformats2::Document object.
59              
60             =item L<Web::Microformats2::Document>
61              
62             Objects are queryable structures of parsed Microformats2 metadata. Each
63             came either fresh from HTML, or re-inflated from its JSON serialization
64             format.
65              
66             =item L<Web::Microformats2::Item>
67              
68             Each document object contains one or more objects of this class. Each
69             item represents a single, "h-"prefixed microformat substructure,
70             defining what we in the Perl world might call some I<thingy>: an
71             article, a person, an invitation, and so on. Each item has some number
72             of properties, and possibly a parent item and a list of child items.
73              
74             =back
75              
76             =head1 STATUS
77              
78             These modules provide a I<reasonably complete> implementation of L<the
79             Microformats2 Living
80             Specification|http://microformats.org/wiki/microformats2-parsing>. They
81             pass all of L<the official MF2 baseline test
82             cases|https://github.com/microformats/tests>, a copy of which is
83             included with these modules' own test suite.
84              
85             The author considers this software B<beta>. Its public interface may
86             still change, but not without some effort at supporting its current API.
87              
88             =head1 ABOUT MICROFORMATS2
89              
90             Microformats2 allows the attachment of semantic metadata to arbitrary
91             HTML elements, in a way that neither hinders the human readability of
92             the underlying HTML document nor strictly prescribes any set vocabulary
93             to this metadata.
94              
95             For example, an HTML page containing several recent blog entries might
96             use Microformats2 to identify the title, date, and content of each
97             entry, as well as its author. It could furthermore define not just the
98             author's name, but also their contact information, homepage URL, and
99             avatar-graphic. It might even identify some entries as public responses
100             to other articles found elsewhere on the web. Since all this metadata
101             exists quietly within the "class" attributes found within the HTML
102             page's ordinary markup, its presence does not affect or interfere with
103             the web page's rendering or readability to humans.
104              
105             A Microfomats2 parser can read these special attribute values --
106             identifiable by their conspicuous use of prefixes, such as "h-entry" and
107             "p-name" -- and turn them into data structures that use this metadata to
108             give additional order, structure, and semantic labeling to the content
109             found within. These data structures can then be passed (usually as JSON
110             strings) to other processors, which can make all sorts of interesting
111             things happen.
112              
113             Microformats2 is the successor to Microformats. While similar in intent
114             and execution, their implementations are very different. Rather than
115             using the pre-defined vocabularies of its predecessor, Microformats2
116             uses a relatively simple set of rules that allow for limitless
117             user-definable labels for metadata items and their constituent
118             properties.
119              
120             For more information about Microformats2, please see
121             L<https://microformats.io>. For a deep dive into the MF2 specification,
122             see L<http://microformats.org/wiki/microformats2>.
123              
124             =head1 SUPPORT
125              
126             To file issues or submit pull requests, please see L<this module's
127             repository on GitHub|https://github.com/jmacdotorg/microformats2-perl>.
128              
129             The author also welcomes any direct questions about this module via email.
130              
131             =head1 AUTHOR
132              
133             Jason McIntosh (jmac@jmac.org)
134              
135             =head1 COPYRIGHT AND LICENSE
136              
137             This software is Copyright (c) 2018 by Jason McIntosh.
138              
139             This is free software, licensed under:
140              
141             The MIT (X11) License
142              
143             =head1 A PERSONAL REQUEST
144              
145             My ability to share and maintain free, open-source software like this
146             depends upon my living in a society that allows me the free time and
147             personal liberty to create work benefiting people other than just myself
148             or my immediate family. I recognize that I got a head start on this due
149             to an accident of birth, and I strive to convert some of my unclaimed
150             time and attention into work that, I hope, gives back to society in some
151             small way.
152              
153             Worryingly, I find myself today living in a country experiencing a
154             profound and unwelcome political upheaval, with its already flawed
155             democracy under grave threat from powerful authoritarian elements. These
156             powers wish to undermine this society, remolding it according to their
157             deeply cynical and strictly zero-sum philosophies, where nobody can gain
158             without someone else losing.
159              
160             Free and open-source software has no place in such a world. As such,
161             these autocrats' further ascension would have a deleterious effect on my
162             ability to continue working for the public good.
163              
164             Therefore, if you would like to financially support my work, I would ask
165             you to consider a donation to one of the following causes. It would mean
166             a lot to me if you did. (You can tell me about it if you'd like to, but
167             you don't have to.)
168              
169             =over
170              
171             =item *
172              
173             L<The American Civil Liberties Union|https://aclu.org>
174              
175             =item *
176              
177             L<The Democratic National Committee|https://democrats.org>
178              
179             =item *
180              
181             L<Earthjustice|https://earthjustice.org>
182              
183             =back