The `system` Lua module provides utility functions to interact with the
operating- and file system. E.g.
print(pandoc.system.get_current_directory())
or
pandoc.system.with_temporary_directory('tikz', function (dir)
-- write and compile a TikZ file with pdflatex
end)
All Lua modules bundled with pandoc, i.e., `pandoc.List`,
`pandoc.mediabag`, `pandoc.utils`, and `text` are re-exported from the
`pandoc` module. They are assigned to the fields `List`, `mediabag`,
`utils`, and `text`, respectively.
Incorrect types to pandoc element constructors are automatically
converted to the correct types when possible. This was already done for
most constructors, but conversions are now also done for nested
types (like lists of lists).
Equality of Lua objects representing pandoc AST elements is tested by
unmarshalling the objects and comparing the result in Haskell. A new
function `equals` which performs this test has been added to the
`pandoc.utils` module.
Closes: #5092
This makes it possible to iterate over all field names of an AST element
by using a generic `for` loop with `pairs`:
for field_name, field_content in pairs(element) do
…
end
Raw table fields of AST elements should be considered an implementation
detail and might change in the future. Accessing element properties
should always happen through the fields listed in the Lua filter docs.
Note that the iterator currently excludes the `t`/`tag` field.
Passing a MetaList object to the constructor `pandoc.MetaList` now
returns the passed list as a MetaList. This is consistent with the
constructor behavior when passed an (untagged) list.
Previously, the constructor used to create a new MetaList with the
passed MetaList as its only element.
Elements with attributes got an additional `attr` accessor. Attributes
were accessible only via the `identifier`, `classes`, and `attributes`,
which was in conflict with the documentation, which indirectly states
that such elements have the an `attr` property.
Every constructor which accepts a list of blocks now also accepts a
single block element for convenience. Furthermore, strings are accepted as
shorthand for `{pandoc.Str "text"}` in constructors.
Accessing an Attr value (e.g., ` Attr().classes`) was broken; the more
common case of accessing it via an Inline or Block element was
unaffected by this.
This attribute was out-of-sync with the actual version as is mostly
irrelevant in the context Lua filters and custom writers. Use the
global `PANDOC_API_VERSION` instead.
*Pandoc*, *Meta*, and *Citation* were just plain functions and did not
set a metatable on the returned value, which made it difficult to amend
objects of these types with new behavior. They are now subtypes of
AstElement, meaning that all their objects can gain new features when a
method is added to the behavior object (e.g., `pandoc.Pandoc.behavior`).
Clearly distinguish between a type and the behavioral properties of an instance
of that type. The behavior of a type (and all its subtypes) can now be amended
by adding methods to that types `behavior` object, without exposing the type
objects internals.
E.g.:
pandoc.Inline.behavior.frob = function () print'42' end
local str = pandoc.Str'hello'
str.frob() -- outputs '42'
Extending all elements of a given type (e.g., all inline elements) was
difficult, as the table used to lookup unknown methods would be reset
every time a new element of that type was created, preventing recursive
property lookup. This is was changed in that all methods and attributes
of supertypes are now available to their subtypes.
The fields were named like the Haskell fields, not like the documented,
shorter version. The names are changed to match the documentation and
Citations are given a shared metatable to enable simple extensibility.
Fixes: #4222
The function `global_filter` was used internally to get the implicitly
defined global filter. It was of little value to end-users, but caused
unnecessary code duplication in pandoc. The function has hence been
dropped. Internally, the global filter is now received by interpreting
the global table as lua filter.
This is a Lua API change.
The `pipe` and `read` utility functions are converted from hybrid
lua/haskell functions into full Haskell functions. This avoids the need
for intermediate `_pipe`/`_read` helper functions, which have dropped.
The integration with Lua's package/module system is improved: A
pandoc-specific package searcher is prepended to the searchers in
`package.searchers`. The modules `pandoc` and `pandoc.mediabag` can now
be loaded via `require`.
The `List` metatable is assigned to the tables which get passed to the
constructors `MetaBlocks`, `MetaInline`, and `MetaList`. This enables
the use of the resulting objects as lists. This is part of the changes
discussed in #4081.
Pandoc and Meta elements are now pushed by calling the respective
constructor functions of the pandoc Lua module. This makes serialization
consistent with the way blocks and inlines are pushed to lua and allows
to use List methods with the `blocks` value.
The List module is automatically loaded, but not assigned to a global
variable. It can be included in filters by calling `List = require
'List'`.
Lists of blocks, lists of inlines, and lists of classes are now given
`List` as a metatable, making working with them more convenient. E.g.,
it is now possible to concatenate lists of inlines using Lua's
concatenation operator `..` (requires at least one of the operants to
have `List` as a metatable):
function Emph (emph)
local s = {pandoc.Space(), pandoc.Str 'emphasized'}
return pandoc.Span(emph.content .. s)
end
Closes: #4081
Attribute lists are represented as associative lists in Lua. Pure
associative lists are awkward to work with. A metatable is attached to
attribute lists, allowing to access and use the associative list as if
the attributes were stored in as normal key-value pair in table.
Note that this changes the way `pairs` works on attribute lists. Instead
of producing integer keys and two-element tables, the resulting iterator
function now returns the key and value of those pairs. Use `ipairs` to
get the old behavior.
Warning: the new iteration mechanism only works if pandoc has been
compiled with Lua 5.2 or later (current default: 5.3).
The `pandoc.Attr` function is altered to allow passing attributes as
key-values in a normal table. This is more convenient than having to
construct the associative list which is used internally.
Closes#4071
The second argument of the OrderedList constructor, which should define
the list's attributes, is made optional. Default attributes are used if
the parameter is omitted.
Make Attr values accessible through through the keys `identifier`,
`classes` and `attributes`. This is already used in other elements with
attributes and is now fixed for Link and Image.
The pipe command is wrapped in a lua function, throwing a lua error if
the command returns with an error. A wrapper is needed as Haskell
functions exposed to lua may not throw lua errors due to limitations of
hslua.
The error handling is written such that a table can be returned as an
error object in the future. This is potentially useful when finer
control is required while catching the error in lua code. Current
limitations of hslua require error objects to be strings.
Functions with a name that corresponds to an AST element are included in
implicit pandoc filter, but both `Meta` and `Pandoc` were wrongly
ignored till now.
Albert Krewinkel