File: README.pod

package info (click to toggle)
librdf-rdfa-generator-perl 0.200-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 252 kB
  • sloc: perl: 885; sh: 4; makefile: 2
file content (257 lines) | stat: -rw-r--r-- 7,815 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
=head1 NAME

RDF::RDFa::Generator - Generate data for RDFa serialization

=cut

package RDF::RDFa::Generator;

use 5.008;
use strict;

use warnings;


our $VERSION = '0.200';

use RDF::RDFa::Generator::HTML::Head;
use RDF::RDFa::Generator::HTML::Hidden;
use RDF::RDFa::Generator::HTML::Pretty;
use Carp;


=head1 DESCRIPTION

=head2 Constructor

=over 4

=item C<< $gen = RDF::RDFa::Generator->new(style => $style, %options) >>

Creates a new generator object. $style is one of the following case-sensitive strings:
'HTML::Head' (the default), 'HTML::Hidden' or 'HTML::Pretty'. You can also construct
an object like this:

  $gen = RDF::RDFa::Generator::HTML::Head->new(%options);

Options include:

=over 4

=item * B<base> - the base URL where the output data will be published. This allows in some cases for the generated RDFa to include relative URIs.

=item * B<data_context> - if non-null, an L<Attean> Blank or IRI object or an L<RDF::Trine::Node> which indicates the context (named graph) containing the data to generate RDFa for.

=item * B<namespacemap> - a L<URI::NamespaceMap> object containing preferred CURIE prefixes. This is the preferred method, see note below. 

=item * B<namespaces> - a {prefix=>uri} hashref of preferred CURIE prefixes. 

=item * B<ns> - a {uri=>prefix} hashref of preferred CURIE prefixes. DEPRECATED - use B<namespaces> instead.

=item * B<prefix_attr> - use the @prefix attribute for CURIE prefixes (RDFa 1.1 only).  Boolean, defaults to false.

=item * B<safe_xml_literals> - prevents XML literals from injecting arbitrary XHTML into the output. Boolean, B<defaults to FALSE>.

=item * B<title> - assign a <title> element for generated XHTML documents.

=item * B<version> - set generated RDFa version. Valid values are '1.0' (the default) or '1.1'.

=back

=back

=cut

sub new
{
	my ($class, %opts) = @_;
	my $implementation = sprintf('%s::%s', __PACKAGE__, $opts{'style'} || 'HTML::Head');
	return $implementation->new(%opts);
}

=head2 Public Methods

=over 4

=item C<< $gen->create_document($model, %opts) >>

Creates a new RDFa file containing triples. $model is an RDF::Trine::Model object
providing the triples. Returns an XML::LibXML::Document object suitable
for serializing using its C<toString> method.

If you're planning on serving the RDFa with the text/html media type, then
it is recommended that you use HTML::HTML5::Writer to serialize the
document rather than C<toString>.

Can also be called as a class method:

 $document = RDF::RDFa::Generator->create_document($model)
 # Same as:
 # $document = RDF::RDFa::Generator->new->create_document($model)

Options can also be passed as a HASH. This is typically used for style-specific options.

=cut

sub create_document
{
	my $proto = shift;
	my $self = (ref $proto) ? $proto : $proto->new;
	return $self->create_document(@_);
}

=item C<< $gen->inject_document($document, $model) >>

Injects an existing document with triples. $document is an XML::LibXML::Document
to inject, or a well-formed XML string. $model is an RDF::Trine::Model object providing
the triples. Returns an XML::LibXML::Document object suitable
for serializing using its C<toString> method.

See C<create_document> for information about serving the RDFa with the
text/html media type.

Can also be called as a class method. See C<create_document> for details.

=cut

sub inject_document
{
	my $proto = shift;
	my $self = (ref $proto) ? $proto : $proto->new;
	return $self->inject_document(@_);
}

=item C<< $gen->nodes($model) >>

Provides triple-laden XML::LibXML::Elements to be added to a document.
$model is an RDF::Trine::Model object providing the triples. If called in
list context, returns a list of XML::LibXML::Element objects which can be
added to a document; otherwise returns an XML::LibXML::NodeList containing
a list of such elements.

Can also be called as a class method. See C<create_document> for details.

The HTML::Pretty generator can be passed a couple of additional options:

  $gen->nodes($model, notes_heading=>'Additional Info', notes=>\@notes);

The notes are a list of RDF::RDFa::Generator::HTML::Pretty::Note objects
which are added as notes to the end of each subject's data.

=cut

sub nodes
{
	my $proto = shift;
	my $self = (ref $proto) ? $proto : $proto->new;
	return $self->nodes(@_);
}

=back

=head1 UPGRADING TO 0.200

The recommended upgrade path is to migrate your application to use
L<Attean> rather than L<RDF::Trine> as your RDF library. If that is
not an option, you may continue to use L<RDF::Trine>, by using a
compatibility layer.  If you are using this module directly, to
upgrade from earlier releases, you would simply add

 use RDF::TrineX::Compatibility::Attean;

alongside the import of this module. It is in a separate distribution
that needs to be installed. If you use the L<RDF::Trine::Serializer>
methods, you should instead use L<RDF::Trine::Serializer::RDFa>.

=head1 NOTE

Version 0.200 introduced a large number of changes to be compatible
with both L<Attean> and L<RDF::Trine>. Some of these were
backwards-incompatible, some were to support new features, such as the
use of L<URI::NamespaceMap>.

=head2 Backwards-incompatible changes

The methods C<serialize_model_to_file>, C<serialize_model_to_string>,
C<serialize_iterator_to_file> and C<serialize_iterator_to_string> that
were provided for compatibility with the L<RDF::Trine::Serializer>
interface have been moved to a module L<RDF::Trine::Serializer::RDFa>
that has to be installed separately to use this with L<RDF::Trine>.

C<data_context> previously accepted a plain-text string URI. Now, it
requires an appropriate object, as documented.

Since RDF 1.1 abandons untyped literals, this module also ceases to
emit them.

=head2 Namespace mappings

The way namespace mappings are handled have been rewritten. Now, the
preferred method to add them is to pass an L<URI::NamespaceMap> object
to C<namespacemap>. This will override any other options.

The namespace mappings for the following prefixes will always be
added: C<rdfa>, C<rdf>, C<rdfs> and C<xsd>.

If L<URI::NamespaceMap> is not used, but C<namespaces> is given as a
hashref of prefix-URI pairs, the pairs will be added. If neither are
given, all mappings from L<RDF::NS::Curated>, which includes all if
RDFa Initial Context will be added. Finally, any pairs from the
deprecated C<ns> option will be added, but a warning will be emitted.

=cut

sub serialize_model_to_string {
  croak 'serialize_model_to_string have been to moved RDF::Trine::Serializer::RDFa';
}

sub serialize_model_to_file {
  croak 'serialize_model_to_file have been to moved RDF::Trine::Serializer::RDFa';
}

sub serialize_iterator_to_string {
  croak 'serialize_iterator_to_string have been to moved RDF::Trine::Serializer::RDFa';
}

sub serialize_iterator_to_file {
  croak 'serialize_iterator_to_string have been to moved RDF::Trine::Serializer::RDFa';
}

1;

__END__

=head1 BUGS

Please report any bugs to L<https://github.com/kjetilk/p5-rdf-rdfa-generator/issues>.

=head1 SEE ALSO

You may want to use the framework-specific frontends: L<RDF::Trine::Serializer::RDFa> or L<AtteanX::Serializer::RDFa>.

Other relevant modules:

L<HTML::HTML5::Writer>, L<XML::LibXML>, L<RDF::RDFa::Parser>, L<RDF::Trine>,
L<URI::NamespaceMap>, L<Attean>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

Kjetil Kjernsmo E<lt>kjetilk@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

Copyright (C) 2010 by Toby Inkster, 2017, 2018 Kjetil Kjernsmo

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8 or,
at your option, any later version of Perl 5 you may have available.

=head2 Icons

RDF::RDFa::Generator::HTML::Pretty uses the FamFamFam Silk icons;
see L<http://famfamfam.com/lab/icons/silk/>.

=cut