@@ -1,6 +1,6 @@
11% Pandoc Lua Filters
22% Albert Krewinkel, John MacFarlane
3−% August 21, 2017
3+% August 31, 2017
44
55# Introduction
66
@@ -111,6 +111,11 @@ inline element must return an inline, and a block element must
111111remain a block element after filter application. Pandoc will
112112throw an error if this condition is violated.
113113
114+If there is no function matching the element's node type, then
115+the filtering system will look for a more general fallback
116+function. Two fallback functions are supported, `Inline` and
117+`Block`. Each matches elements of the respective type.
118+
114119Elements without matching functions are left untouched.
115120
116121See [module documentation](pandoc-module.html) for a list of pandoc
@@ -304,3 +309,738 @@ then running `pandoc --lua-filter=meta-vars.lua occupations.md` will output:
304309</dd>
305310</dl>
306311```
312+
313+# Module pandoc
314+
315+Lua functions for pandoc scripts.
316+
317+## Pandoc Document
318+
319+[`Pandoc (blocks[, meta])`]{#Pandoc}
320+
321+: A complete pandoc document
322+
323+ Parameters:
324+
325+ `blocks`:
326+ : document content
327+
328+ `meta`:
329+ : document meta data
330+
331+## MetaValue
332+
333+[`MetaBlocks (blocks)`]{#MetaBlocks}
334+
335+: Meta blocks
336+
337+ Parameters:
338+
339+ `blocks`:
340+ : blocks
341+
342+[`MetaInlines (inlines)`]{#MetaInlines}
343+
344+: Meta inlines
345+
346+ Parameters:
347+
348+ `inlines`:
349+ : inlines
350+
351+[`MetaList (meta_values)`]{#MetaList}
352+
353+: Meta list
354+
355+ Parameters:
356+
357+ `meta_values`:
358+ : list of meta values
359+
360+[`MetaMap (key_value_map)`]{#MetaMap}
361+
362+: Meta map
363+
364+ Parameters:
365+
366+ `key_value_map`:
367+ : a string-indexed map of meta values
368+
369+[`MetaString (str)`]{#MetaString}
370+
371+: Creates string to be used in meta data.
372+
373+ Parameters:
374+
375+ `str`:
376+ : string value
377+
378+[`MetaBool (bool)`]{#MetaBool}
379+
380+: Creates boolean to be used in meta data.
381+
382+ Parameters:
383+
384+ `bool`:
385+ : boolean value
386+
387+## Blocks
388+
389+[`Block`]{#Block}
390+
391+: Block elements
392+
393+[`BlockQuote (content)`]{#BlockQuote}
394+
395+: Creates a block quote element
396+
397+ Parameters:
398+
399+ `content`:
400+ : block content
401+
402+ Returns: block quote element
403+
404+[`BulletList (content)`]{#BulletList}
405+
406+: Creates a bullet (i.e.
407+
408+ Parameters:
409+
410+ `content`:
411+ : list of items
412+
413+ Returns: block quote element
414+
415+[`CodeBlock (text[, attr])`]{#CodeBlock}
416+
417+: Creates a code block element
418+
419+ Parameters:
420+
421+ `text`:
422+ : code string
423+
424+ `attr`:
425+ : element attributes
426+
427+ Returns: code block element
428+
429+[`DefinitionList (content)`]{#DefinitionList}
430+
431+: Creates a definition list, containing terms and their
432+ explanation.
433+
434+ Parameters:
435+
436+ `content`:
437+ : list of items
438+
439+ Returns: block quote element
440+
441+[`Div (content[, attr])`]{#Div}
442+
443+: Creates a div element
444+
445+ Parameters:
446+
447+ `content`:
448+ : block content
449+
450+ `attr`:
451+ : element attributes
452+
453+ Returns: code block element
454+
455+[`Header (level, content[, attr])`]{#Header}
456+
457+: Creates a block quote element.
458+
459+ Parameters:
460+
461+ `level`:
462+ : header level
463+
464+ `content`:
465+ : inline content
466+
467+ `attr`:
468+ : element attributes
469+
470+ Returns: header element
471+
472+[`HorizontalRule ()`]{#HorizontalRule}
473+
474+: Creates a horizontal rule.
475+
476+ Returns: horizontal rule
477+
478+[`LineBlock (content)`]{#LineBlock}
479+
480+: Creates a line block element.
481+
482+ Parameters:
483+
484+ `content`:
485+ : inline content
486+
487+ Returns: block quote element
488+
489+[`Null ()`]{#Null}
490+
491+: Creates a null element.
492+
493+ Returns: null element
494+
495+[`OrderedList (items[, listAttributes])`]{#OrderedList}
496+
497+: Creates an ordered list.
498+
499+ Parameters:
500+
501+ `items`:
502+ : list items
503+
504+ `listAttributes`:
505+ : list parameters
506+
507+ Returns:
508+
509+[`Para (content)`]{#Para}
510+
511+: Creates a para element.
512+
513+ Parameters:
514+
515+ `content`:
516+ : inline content
517+
518+ Returns: block quote element
519+
520+[`Plain (content)`]{#Plain}
521+
522+: Creates a plain element.
523+
524+ Parameters:
525+
526+ `content`:
527+ : inline content
528+
529+ Returns: block quote element
530+
531+[`RawBlock (format, text)`]{#RawBlock}
532+
533+: Creates a raw content block of the specified format.
534+
535+ Parameters:
536+
537+ `format`:
538+ : format of content
539+
540+ `text`:
541+ : string content
542+
543+ Returns: block quote element
544+
545+[`Table (caption, aligns, widths, headers, rows)`]{#Table}
546+
547+: Creates a table element.
548+
549+ Parameters:
550+
551+ `caption`:
552+ : table caption
553+
554+ `aligns`:
555+ : alignments
556+
557+ `widths`:
558+ : column widths
559+
560+ `headers`:
561+ : header row
562+
563+ `rows`:
564+ : table rows
565+
566+ Returns: block quote element
567+
568+## Inline
569+
570+[`Inline`]{#Inline}
571+
572+: Inline element class
573+
574+[`Cite (content, citations)`]{#Cite}
575+
576+: Creates a Cite inline element
577+
578+ Parameters:
579+
580+ `content`:
581+ : List of inlines
582+
583+ `citations`:
584+ : List of citations
585+
586+ Returns: citations element
587+
588+[`Code (text[, attr])`]{#Code}
589+
590+: Creates a Code inline element
591+
592+ Parameters:
593+
594+ `text`:
595+ : brief image description
596+
597+ `attr`:
598+ : additional attributes
599+
600+ Returns: code element
601+
602+[`Emph (content)`]{#Emph}
603+
604+: Creates an inline element representing emphasised text.
605+
606+ Parameters:
607+
608+ `content`:
609+ : inline content
610+
611+ Returns: emphasis element
612+
613+[`Image (caption, src[, title[, attr]])`]{#Image}
614+
615+: Creates a Image inline element
616+
617+ Parameters:
618+
619+ `caption`:
620+ : text used to describe the image
621+
622+ `src`:
623+ : path to the image file
624+
625+ `title`:
626+ : brief image description
627+
628+ `attr`:
629+ : additional attributes
630+
631+ Returns: image element
632+
633+[`LineBreak ()`]{#LineBreak}
634+
635+: Create a LineBreak inline element
636+
637+ Returns: linebreak element
638+
639+[`Link (content, target[, title[, attr]])`]{#Link}
640+
641+: Creates a link inline element, usually a hyperlink.
642+
643+ Parameters:
644+
645+ `content`:
646+ : text for this link
647+
648+ `target`:
649+ : the link target
650+
651+ `title`:
652+ : brief link description
653+
654+ `attr`:
655+ : additional attributes
656+
657+ Returns: image element
658+
659+[`Math (mathtype, text)`]{#Math}
660+
661+: Creates a Math element, either inline or displayed.
662+
663+ Parameters:
664+
665+ `mathtype`:
666+ : rendering specifier
667+
668+ `text`:
669+ : Math content
670+
671+ Returns: Math element
672+
673+[`DisplayMath (text)`]{#DisplayMath}
674+
675+: Creates a DisplayMath element (DEPRECATED).
676+
677+ Parameters:
678+
679+ `text`:
680+ : Math content
681+
682+ Returns: Math element
683+
684+[`InlineMath (text)`]{#InlineMath}
685+
686+: Creates an InlineMath inline element (DEPRECATED).
687+
688+ Parameters:
689+
690+ `text`:
691+ : Math content
692+
693+ Returns: Math element
694+
695+[`Note (content)`]{#Note}
696+
697+: Creates a Note inline element
698+
699+ Parameters:
700+
701+ `content`:
702+ : footnote block content
703+
704+[`Quoted (quotetype, content)`]{#Quoted}
705+
706+: Creates a Quoted inline element given the quote type and
707+ quoted content.
708+
709+ Parameters:
710+
711+ `quotetype`:
712+ : type of quotes to be used
713+
714+ `content`:
715+ : inline content
716+
717+ Returns: quoted element
718+
719+[`SingleQuoted (content)`]{#SingleQuoted}
720+
721+: Creates a single-quoted inline element (DEPRECATED).
722+
723+ Parameters:
724+
725+ `content`:
726+ : inline content
727+
728+ Returns: quoted element
729+
730+ See also: [Quoted](#Quoted)
731+
732+[`DoubleQuoted (content)`]{#DoubleQuoted}
733+
734+: Creates a single-quoted inline element (DEPRECATED).
735+
736+ Parameters:
737+
738+ `content`:
739+ : inline content
740+
741+ Returns: quoted element
742+
743+ See also: [Quoted](#Quoted)
744+
745+[`RawInline (format, text)`]{#RawInline}
746+
747+: Creates a RawInline inline element
748+
749+ Parameters:
750+
751+ `format`:
752+ : format of the contents
753+
754+ `text`:
755+ : string content
756+
757+ Returns: raw inline element
758+
759+[`SmallCaps (content)`]{#SmallCaps}
760+
761+: Creates text rendered in small caps
762+
763+ Parameters:
764+
765+ `content`:
766+ : inline content
767+
768+ Returns: smallcaps element
769+
770+[`SoftBreak ()`]{#SoftBreak}
771+
772+: Creates a SoftBreak inline element.
773+
774+ Returns: softbreak element
775+
776+[`Space ()`]{#Space}
777+
778+: Create a Space inline element
779+
780+ Returns: space element
781+
782+[`Span (content[, attr])`]{#Span}
783+
784+: Creates a Span inline element
785+
786+ Parameters:
787+
788+ `content`:
789+ : inline content
790+
791+ `attr`:
792+ : additional attributes
793+
794+ Returns: span element
795+
796+[`Str (text)`]{#Str}
797+
798+: Creates a Str inline element
799+
800+ Parameters:
801+
802+ `text`:
803+ : content
804+
805+ Returns: string element
806+
807+[`Strikeout (content)`]{#Strikeout}
808+
809+: Creates text which is striked out.
810+
811+ Parameters:
812+
813+ `content`:
814+ : inline content
815+
816+ Returns: strikeout element
817+
818+[`Strong (content)`]{#Strong}
819+
820+: Creates a Strong element, whose text is usually displayed in
821+ a bold font.
822+
823+ Parameters:
824+
825+ `content`:
826+ : inline content
827+
828+ Returns: strong element
829+
830+[`Subscript (content)`]{#Subscript}
831+
832+: Creates a Subscript inline element
833+
834+ Parameters:
835+
836+ `content`:
837+ : inline content
838+
839+ Returns: subscript element
840+
841+[`Superscript (content)`]{#Superscript}
842+
843+: Creates a Superscript inline element
844+
845+ Parameters:
846+
847+ `content`:
848+ : inline content
849+
850+ Returns: strong element
851+
852+## Helpers
853+
854+[`Attr ([identifier[, classes[, attributes]]])`]{#Attr}
855+
856+: Create a new set of attributes (Attr).
857+
858+ Parameters:
859+
860+ `identifier`:
861+ : element identifier
862+
863+ `classes`:
864+ : element classes
865+
866+ `attributes`:
867+ : table containing string keys and values
868+
869+ Returns: element attributes
870+
871+[`Citation (id, mode[, prefix[, suffix[, note_num[, hash]]]])`]{#Citation}
872+
873+: Creates a single citation.
874+
875+ Parameters:
876+
877+ `id`:
878+ : citation identifier (like a bibtex key)
879+
880+ `mode`:
881+ : citation mode
882+
883+ `prefix`:
884+ : citation prefix
885+
886+ `suffix`:
887+ : citation suffix
888+
889+ `note_num`:
890+ : note number
891+
892+ `hash`:
893+ : hash number
894+
895+## Constants
896+
897+[`AuthorInText`]{#AuthorInText}
898+
899+: Author name is mentioned in the text.
900+
901+ See also: [Citation](#Citation)
902+
903+[`SuppressAuthor`]{#SuppressAuthor}
904+
905+: Author name is suppressed.
906+
907+ See also: [Citation](#Citation)
908+
909+[`NormalCitation`]{#NormalCitation}
910+
911+: Default citation style is used.
912+
913+ See also: [Citation](#Citation)
914+
915+[`AlignLeft`]{#AlignLeft}
916+
917+: Table cells aligned left.
918+
919+ See also: [Table](#Table)
920+
921+[`AlignRight`]{#AlignRight}
922+
923+: Table cells right-aligned.
924+
925+ See also: [Table](#Table)
926+
927+[`AlignCenter`]{#AlignCenter}
928+
929+: Table cell content is centered.
930+
931+ See also: [Table](#Table)
932+
933+[`AlignDefault`]{#AlignDefault}
934+
935+: Table cells are alignment is unaltered.
936+
937+ See also: [Table](#Table)
938+
939+[`DefaultDelim`]{#DefaultDelim}
940+
941+: Default list number delimiters are used.
942+
943+ See also: [OrderedList](#OrderedList)
944+
945+[`Period`]{#Period}
946+
947+: List numbers are delimited by a period.
948+
949+ See also: [OrderedList](#OrderedList)
950+
951+[`OneParen`]{#OneParen}
952+
953+: List numbers are delimited by a single parenthesis.
954+
955+ See also: [OrderedList](#OrderedList)
956+
957+[`TwoParens`]{#TwoParens}
958+
959+: List numbers are delimited by a double parentheses.
960+
961+ See also: [OrderedList](#OrderedList)
962+
963+[`DefaultStyle`]{#DefaultStyle}
964+
965+: List are numbered in the default style
966+
967+ See also: [OrderedList](#OrderedList)
968+
969+[`Example`]{#Example}
970+
971+: List items are numbered as examples.
972+
973+ See also: [OrderedList](#OrderedList)
974+
975+[`Decimal`]{#Decimal}
976+
977+: List are numbered using decimal integers.
978+
979+ See also: [OrderedList](#OrderedList)
980+
981+[`LowerRoman`]{#LowerRoman}
982+
983+: List are numbered using lower-case roman numerals.
984+
985+ See also: [OrderedList](#OrderedList)
986+
987+[`UpperRoman`]{#UpperRoman}
988+
989+: List are numbered using upper-case roman numerals
990+
991+ See also: [OrderedList](#OrderedList)
992+
993+[`LowerAlpha`]{#LowerAlpha}
994+
995+: List are numbered using lower-case alphabetic characters.
996+
997+ See also: [OrderedList](#OrderedList)
998+
999+[`UpperAlpha`]{#UpperAlpha}
1000+
1001+: List are numbered using upper-case alphabetic characters.
1002+
1003+ See also: [OrderedList](#OrderedList)
1004+
1005+## Helper Functions
1006+
1007+[`read (markup[, format])`]{#read}
1008+
1009+: Parse the given string into a Pandoc document.
1010+
1011+ Parameters:
1012+
1013+ `markup`:
1014+ : the markup to be parsed
1015+
1016+ `format`:
1017+ : format specification, defaults to \"markdown\".
1018+
1019+ Returns: pandoc document
1020+
1021+ Usage:
1022+
1023+ local org_markup = "/emphasis/" -- Input to be read
1024+ local document = pandoc.read(org_markup, "org")
1025+ -- Get the first block of the document
1026+ local block = document.blocks[1]
1027+ -- The inline element in that block is an `Emph`
1028+ assert(block.content[1].t == "Emph")
1029+
1030+[`global_filter ()`]{#global_filter}
1031+
1032+: Use functions defined in the global namespace to create a
1033+ pandoc filter.
1034+
1035+ Returns: A list of filter functions
1036+
1037+ Usage:
1038+
1039+ -- within a file defining a pandoc filter:
1040+ function Str(text)
1041+ return pandoc.Str(utf8.upper(text))
1042+ end
1043+
1044+ return {pandoc.global_filter()}
1045+ -- the above is equivallent to
1046+ -- return {{Str = Str}}