Debian Codegraph @

README

raw
1 NAME
2
3 Pandoc::Elements - create and process Pandoc documents
4
5 SYNOPSIS
6
7 The output of this script hello.pl
8
9 use Pandoc::Elements;
10 use JSON;
11
12 print Document(
13 {
14 title => MetaInlines [ Str "Greeting" ]
15 },
16 [
17 Header( 1, attributes { id => 'top' }, [ Str 'Hello' ] ),
18 Para [ Str 'Hello, world!' ],
19 ],
20 api_version => '1.17.0.4'
21 )->to_json;
22
23 can be converted for instance to HTML via
24
25 ./hello.pl | pandoc -f json -t html5 --standalone
26
27 an equivalent Pandoc Markdown document would be
28
29 % Greeting
30 # Gruß {.de}
31 Hello, world!
32
33 DESCRIPTION
34
35 Pandoc::Elements provides utility functions to parse, serialize, and
36 modify abstract syntax trees (AST) of Pandoc <http://pandoc.org/>
37 documents. Pandoc can convert this data structure to many other
38 document formats, such as HTML, LaTeX, ODT, and ePUB.
39
40 See also module Pandoc::Filter, command line script pod2pandoc, and the
41 internal modules Pandoc::Walker and Pod::Simple::Pandoc.
42
43 PANDOC VERSIONS
44
45 The Pandoc document model is defined in file Text.Pandoc.Definition
46 <https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html>
47 as part of Haskell package pandoc-types.
48
49 Pandoc::Elements is compatible with pandoc-types 1.12.3 (released with
50 pandoc 1.12.1) up to at least pandoc-types-1.17.0.4 (first releases
51 with pandoc 1.18). JSON output of all pandoc releases since 1.12.1 can
52 be parsed with function pandoc_json, the "Document" constructor or
53 method parse of module Pandoc. The AST is always upgraded to
54 pandoc-types 1.17 and downgraded to another api version on
55 serialization with to_json.
56
57 To determine the api version required by a version of pandoc executable
58 since version 1.18 execute pandoc with the --version option and check
59 which version of the pandoc-types library pandoc was compiled with.
60
61 Beginning with version 1.18 pandoc will not decode a JSON AST
62 representation unless the major and minor version numbers (Document
63 method api_version) match those built into that version of pandoc. The
64 following changes in pandoc document model have been implemented:
65
66 * pandoc-types 1.17, released for pandoc 1.18, introduced the
67 LineBlock element and modified representation of the root Document
68 element.
69
70 * pandoc-types 1.16, released with pandoc 1.16, introduced attributes
71 to Link and Image elements
72
73 * pandoc-types 1.12.3, released with pandoc 1.12.1, modified the
74 representation of elements to objects with field t and c. This is
75 also the internal representation of documents used in this module.
76
77 FUNCTIONS
78
79 The following functions and keywords are exported by default:
80
81 * Constructors for all Pandoc document element (block elements such
82 as Para and inline elements such as Emph, metadata elements and the
83 Document).
84
85 * Type keywords such as Decimal and LowerAlpha to be used as types in
86 other document elements.
87
88 * The following helper functions pandoc_json, pandoc_version,
89 attributes, metadata, citation, and element.
90
91 pandoc_json $json
92
93 Parse a JSON string, as emitted by pandoc in JSON format. This is the
94 reverse to method to_json but it can read both old (before Pandoc 1.16)
95 and new format.
96
97 attributes { key => $value, ... }
98
99 Maps a hash reference or instance of Hash::MultiValue into the internal
100 structure of Pandoc attributes. The special keys id (string), and class
101 (string or array reference with space-separated class names) are
102 recognized. See attribute methods for details.
103
104 citation { ... }
105
106 A citation as part of document element Cite must be a hash reference
107 with fields citationId (string), citationPrefix (list of inline
108 elements) citationSuffix (list of inline elements), citationMode (one
109 of NormalCitation, AuthorInText, SuppressAuthor), citationNoteNum
110 (integer), and citationHash (integer). The helper method citation can
111 be used to construct such a hash by filling in default values and
112 optionally using shorter field names (id, prefix, suffix, mode, note,
113 and hash):
114
115 citation {
116 id => 'foo',
117 prefix => [ Str "see" ],
118 suffix => [ Str "p.", Space, Str "42" ]
119 }
120
121 # in Pandoc Markdown
122
123 [see @foo p. 42]
124
125 The values returned by this function, as well as any citations
126 contained in document objects returned by pandoc_json, are blessed
127 hashrefs with getter/setter accessors corresponding to both the full
128 and short field names, so that e.g. $citation->citationId(...) and
129 $citation->id(...) get or set the same value.
130
131 pandoc_version( [ $document ] )
132
133 Return a Pandoc::Version object with expected version number of pandoc
134 executable to be used for serializing documents with to_json.
135
136 If a Document element is given as argument, the minimal pandoc release
137 version compatible with its api version is returned.
138
139 Without argument, package variable $PANDOC_VERSION is checked for a
140 preferred pandoc release. By default this variable is set from an
141 environment variable of same name. If no preferred pandoc release has
142 been specified, the function returns version 1.18 because this is the
143 first pandoc release compatible with most recent api version supported
144 by this module.
145
146 See also method version of module Pandoc to get the current version of
147 pandoc executable on your system.
148
149 element( $name => $content )
150
151 Create a Pandoc document element of arbitrary name. This function is
152 only exported on request.
153
154 ELEMENTS AND METHODS
155
156 Document elements are encoded as Perl data structures equivalent to the
157 JSON structure, emitted with pandoc output format json. This JSON
158 structure is subject to minor changes between versions of pandoc. All
159 elements are blessed objects that provide common element methods (all
160 elements), attribute methods (elements with attributes), and additional
161 element-specific methods.
162
163 COMMON METHODS
164
165 to_json
166
167 Return the element as JSON encoded string. The following are
168 equivalent:
169
170 $element->to_json;
171 JSON->new->utf8->canonical->convert_blessed->encode($element);
172
173 The serialization format can be adjusted to different pandoc versions
174 with module and environment variable PANDOC_VERSION or with Document
175 element properties api_version and pandoc_version.
176
177 When writing filters you can normally just rely on the api version
178 value obtained from pandoc, since pandoc expects to receive the same
179 JSON format as it emits.
180
181 name
182
183 Return the name of the element, e.g. "Para" for a paragraph element.
184
185 content
186
187 Return the element content. For most elements (Para, Emph, Str...) the
188 content is an array reference with child elements. Other elements
189 consist of multiple parts; for instance the Link element has attributes
190 (attr, id, class, classes, keyvals) a link text (content) and a link
191 target (target) with url and title.
192
193 is_block
194
195 True if the element is a Block element
196
197 is_inline
198
199 True if the element is an inline Inline element
200
201 is_meta
202
203 True if the element is a Metadata element
204
205 is_document
206
207 True if the element is a Document element
208
209 as_block
210
211 Return the element unmodified if it is a block element or wrapped in a
212 Plain or Div otherwise.
213
214 match( $selector )
215
216 Check whether the element matches a given Pandoc::Selector (given as
217 instance or string).
218
219 walk(...)
220
221 Walk the element tree with Pandoc::Walker
222
223 query(...)
224
225 Query the element to extract results with Pandoc::Walker
226
227 transform(...)
228
229 Transform the element tree with Pandoc::Walker
230
231 string
232
233 Returns a concatenated string of element content, leaving out all
234 formatting.
235
236 ATTRIBUTE METHODS
237
238 Some elements have attributes which can be an identifier, ordered class
239 names and ordered key-value pairs. Elements with attributes provide the
240 following methods:
241
242 attr
243
244 Get or set the attributes in Pandoc internal structure:
245
246 [ $id, [ @classes ], [ [ key => $value ], ... ] ]
247
248 See helper function attributes to create this structure.
249
250 keyvals
251
252 Get all attributes (id, class, and key-value pairs) as new
253 Hash::MultiValue instance, or replace all key-value pairs plus id
254 and/or class if these are included as field names. All class fields are
255 split by whitespaces.
256
257 $e->keyvals # return new Hash::MultiValue
258 $e->keyvals( $HashMultiValue ) # update by instance of Hash::MultiValue
259 $e->keyvals( key => $value, ... ) # update by list of key-value pairs
260 $e->keyvals( \%hash ) # update by hash reference
261 $e->keyvals( { } ) # remove all key-value pairs
262 $e->keyvals( id => '', class => '' ) # remove all key-value pairs, id, class
263
264 id
265
266 Get or set the identifier. See also Pandoc::Filter::HeaderIdentifiers
267 for utility functions to handle Header identifiers.
268
269 class
270
271 Get or set the list of classes, separated by whitespace.
272
273 add_attribute( $name => $value )
274
275 Append an attribute. The special attribute names id and class set or
276 append identifier or class, respectively.
277
278 DOCUMENT ELEMENT
279
280 Document
281
282 Root element, consisting of metadata hash (meta), document element
283 array (content=blocks) and optional api_version. The constructor
284 accepts either two arguments and an optional named parameter
285 api_version:
286
287 Document { %meta }, [ @blocks ], api_version => $version_string
288
289 or a hash with three fields for metadata, document content, and an
290 optional pandoc API version:
291
292 {
293 meta => { %metadata },
294 blocks => [ @content ],
295 pandoc-api-version => [ $major, $minor, $revision ]
296 }
297
298 The latter form is used as pandoc JSON format since pandoc release
299 1.18. If no api version is given, it will be set 1.17 which was also
300 introduced with pandoc release 1.18.
301
302 A third ("old") form is accepted for compatibility with pandoc JSON
303 format before release 1.18 and since release 1.12.1: an array with two
304 elements for metadata and document content respectively.
305
306 [ { unMeta => { %meta } }, [ @blocks ] ]
307
308 The api version is set to 1.16 in this case, but older versions down to
309 1.12.3 used the same format.
310
311 Document elements provide the following special methods in addition to
312 common element methods:
313
314 api_version( [ $api_version ] )
315
316 Return the pandoc-types version (aka "pandoc-api-version") of this
317 document as Pandoc::Version object or sets it to a new value. This
318 version determines how method to_json serializes the document.
319
320 See "PANDOC VERSIONS" for details.
321
322 pandoc_version( [ $pandoc_version ] )
323
324 Return the minimum required version of pandoc executable compatible
325 with the api_version of this document. The following are equivalent:
326
327 $doc->pandoc_version;
328 pandoc_version( $doc );
329
330 If used as setter, sets the api version of this document to be
331 compatible with the given pandoc version.
332
333 content or blocks
334
335 Get or set the array of block elements of the document.
336
337 meta( [ $metadata ] )
338
339 Get and/or set combined document metadata. Use method value to get
340 selected metadata fields and values.
341
342 value( [ $pointer ] [ %options ] )
343
344 Get selected document metadata field value(s). See Pandoc::Metadata
345 for documentation. Can also be called as metavalue, so the following
346 are equivalent:
347
348 $doc->value( ... );
349 $doc->meta->value( ... );
350 $doc->metavalue( ... );
351
352 to_pandoc( [ [ $pandoc, ] @arguments ])
353
354 Process the document with Pandoc executable and return its output:
355
356 $doc->to_pandoc( -o => 'doc.html' );
357 my $markdown = $doc->to_pandoc( -t => 'markdown' );
358
359 The first argument can optionally be an instance of Pandoc to use a
360 specific executable.
361
362 to_...( [ @arguments ] )
363
364 Process the document into markdown (pandoc's extended Markdown),
365 latex (LaTeX), html (HTML), rst (reStructuredText), or plain (plain
366 text). The following are equivalent:
367
368 $doc->to_markdown( @args );
369 $doc->to_pandoc( @args, '-t' => 'markdown' );
370
371 outline( [ $depth ] )
372
373 Returns an outline of the document structure based on Header
374 elements. The outline is a hierarchical hash reference with the
375 following fields:
376
377 header
378
379 Header element (not included at the document root)
380
381 blocks
382
383 List of block elements before the next Header element (of given
384 depth or less if a maximum depth was given)
385
386 sections
387
388 List of subsections, each having the same outline structure.
389
390 BLOCK ELEMENTS
391
392 BlockQuote
393
394 Block quote, consisting of a list of blocks (content)
395
396 BlockQuote [ @blocks ]
397
398 BulletList
399
400 Unnumbered list of items (content=items), each a list of blocks
401
402 BulletList [ [ @blocks ] ]
403
404 CodeBlock
405
406 Code block (literal string content) with attributes (attr, id, class,
407 classes, keyvals)
408
409 CodeBlock $attributes, $content
410
411 DefinitionList
412
413 Definition list, consisting of a list of pairs (content=items), each a
414 term (term, a list of inlines) and one or more definitions
415 (definitions, a list of blocks).
416
417 DefinitionList [ @definitions ]
418
419 # each item in @definitions being a pair of the form
420
421 [ [ @inlines ], [ @blocks ] ]
422
423 Div
424
425 Generic container of blocks (content) with attributes (attr, id, class,
426 classes, keyvals).
427
428 Div $attributes, [ @blocks ]
429
430 Header
431
432 Header with level (integer), attributes (attr, id, class, classes,
433 keyvals), and text (content, a list of inlines).
434
435 Header $level, $attributes, [ @inlines ]
436
437 HorizontalRule
438
439 Horizontal rule
440
441 HorizontalRule
442
443 LineBlock
444
445 List of lines (content), each a list of inlines.
446
447 LineBlock [ @lines ]
448
449 This element was added in pandoc 1.18. Before it was represented Para
450 elements with embedded LineBreak elements. This old serialization form
451 can be enabled by setting $PANDOC_VERSION package variable to a lower
452 version number.
453
454 Null
455
456 Nothing
457
458 Null
459
460 OrderedList
461
462 Numbered list of items (content=items), each a list of blocks),
463 preceded by list attributes (start number, numbering style, and
464 delimiter).
465
466 OrderedList [ $start, $style, $delim ], [ [ @blocks ] ]
467
468 Supported styles are DefaultStyle, Example, Decimal, LowerRoman,
469 UpperRoman, LowerAlpha, and UpperAlpha.
470
471 Supported delimiters are DefaultDelim, Period, OneParen, and TwoParens.
472
473 Para
474
475 Paragraph, consisting of a list of Inline elements (content).
476
477 Para [ $elements ]
478
479 Plain
480
481 Plain text, not a paragraph, consisting of a list of Inline elements
482 (content).
483
484 Plain [ @inlines ]
485
486 RawBlock
487
488 Raw block with format and content string.
489
490 RawBlock $format, $content
491
492 Table
493
494 Table, with caption, column alignments, relative column widths (0 =
495 default), column headers (each a list of blocks), and rows (each a list
496 of lists of blocks).
497
498 Table [ @inlines ], [ @alignments ], [ @width ], [ @headers ], [ @rows ]
499
500 Possible alignments are AlignLeft, AlignRight, AlignCenter, and
501 AlignDefault.
502
503 An example:
504
505 Table [Str "Example"], [AlignLeft,AlignRight], [0.0,0.0],
506 [[Plain [Str "name"]]
507 ,[Plain [Str "number"]]],
508 [[[Plain [Str "Alice"]]
509 ,[Plain [Str "42"]]]
510 ,[[Plain [Str "Bob"]]
511 ,[Plain [Str "23"]]]];
512
513 INLINE ELEMENTS
514
515 Cite
516
517 Citation, a list of citations and a list of inlines (content). See
518 helper function citation to construct citations.
519
520 Cite [ @citations ], [ @inlines ]
521
522 Code
523
524 Inline code, a literal string (content) with attributes (attr, id,
525 class, classes, keyvals)
526
527 Code attributes { %attr }, $content
528
529 Emph
530
531 Emphasized text, a list of inlines (content).
532
533 Emph [ @inlines ]
534
535 Image
536
537 Image with alt text (content, a list of inlines) and target (list of
538 url and title) with attributes (attr, id, class, classes, keyvals).
539
540 Image attributes { %attr }, [ @inlines ], [ $url, $title ]
541
542 Serializing the attributes is disabled in api version less then 1.16.
543
544 LineBreak
545
546 Hard line break
547
548 LineBreak
549
550 Link
551
552 Hyperlink with link text (content, a list of inlines) and target (list
553 of url and title) with attributes (attr, id, class, classes, keyvals).
554
555 Link attributes { %attr }, [ @inlines ], [ $url, $title ]
556
557 Serializing the attributes is disabled in api version less then 1.16.
558
559 Math
560
561 TeX math, given as literal string (content) with type (one of
562 DisplayMath and InlineMath).
563
564 Math $type, $content
565
566 Note
567
568 Footnote or Endnote, a list of blocks (content).
569
570 Note [ @blocks ]
571
572 Quoted
573
574 Quoted text with quote type (one of SingleQuote and DoubleQuote) and a
575 list of inlines (content).
576
577 Quoted $type, [ @inlines ]
578
579 RawInline
580
581 Raw inline with format (a string) and content (a string).
582
583 RawInline $format, $content
584
585 SmallCaps
586
587 Small caps text, a list of inlines (content).
588
589 SmallCaps [ @inlines ]
590
591 SoftBreak
592
593 Soft line break
594
595 SoftBreak
596
597 This element was added in pandoc 1.16 as a matter of editing
598 convenience to preserve line breaks (as opposed to paragraph breaks)
599 from input source to output. If you are going to feed a document
600 containing SoftBreak elements to Pandoc < 1.16 you will have to set the
601 package variable or environment variable PANDOC_VERSION to 1.15 or
602 below.
603
604 Space
605
606 Inter-word space
607
608 Space
609
610 Span
611
612 Generic container of inlines (content) with attributes (attr, id,
613 class, classes, keyvals).
614
615 Span attributes { %attr }, [ @inlines ]
616
617 Str
618
619 Plain text, a string (content).
620
621 Str $content
622
623 Strikeout
624
625 Strikeout text, a list of inlines (content).
626
627 Strikeout [ @inlines ]
628
629 Strong
630
631 Strongly emphasized text, a list of inlines (content).
632
633 Strong [ @inlines ]
634
635 Subscript
636
637 Subscripted text, a list of inlines (content).
638
639 Supscript [ @inlines ]
640
641 Superscript
642
643 Superscripted text, a list of inlines (content).
644
645 Superscript [ @inlines ]
646
647 METADATA ELEMENTS
648
649 See Pandoc::Metadata for documentation of metadata elements MetaBool,
650 MetaString, MetaMap, MetaInlines, MetaList, and MetaBlocks.
651
652 Helper function metadata can be used to convert scalars, hash
653 references, array references, and Pandoc Inline/Block elements into
654 metadata elements.
655
656 TYPE KEYWORDS
657
658 The following document elements are only as used as type keywords in
659 other document elements:
660
661 * SingleQuote, DoubleQuote
662
663 * DisplayMath, InlineMath
664
665 * AuthorInText, SuppressAuthor, NormalCitation
666
667 * AlignLeft, AlignRight, AlignCenter, AlignDefault
668
669 * DefaultStyle, Example, Decimal, LowerRoman, UpperRoman, LowerAlpha,
670 UpperAlpha
671
672 * DefaultDelim, Period, OneParen, TwoParens
673
674 SEE ALSO
675
676 Perl module Pandoc implements a wrapper around the pandoc executable.
677
678 Similar libraries in other programming languages are listed at
679 https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces.
680
681 AUTHOR
682
683 Jakob Voß <[email protected]>
684
685 CONTRIBUTORS
686
687 Benct Philip Jonsson <[email protected]>
688
689 TakeAsk <https://github.com/TakeAsh>
690
691 COPYRIGHT AND LICENSE
692
693 Copyright 2014- Jakob Voß
694
695 GNU General Public License, Version 2
696
697 This module is heavily based on Pandoc by John MacFarlane.
698