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.
The Attr argument is made optional for all pandoc element constructors
which take such a parameter. The attr param is always the last argument
of the constructor functions, so the option to omit them makes it easier
to construct new pandoc elements by hand.
The implicitly defined global filter (i.e. all element filtering
functions defined in the global lua environment) is used if no filter is
returned from a lua script. This allows to just write top-level
functions in order to define a lua filter. E.g
function Emph(elem) return pandoc.Strong(elem.content) end
Attributes was written to behave much like a normal table, in order to
simplify working with it. However, all Attr containing elements were
changed to provide panflute-like accessors to Attr components, rendering
the previous approach unnecessary.
A single `read` function parsing pandoc-supported formats is added to
the module. This is simpler and more convenient than the previous method
of exposing all reader functions individually.
Meta elements that are treated as lua tables (i.e. MetaList,
MetaInlines, MetaBlocks, and MetaMap), are no longer wrapped in an
additional table but simply marked via a metatable. This allows
treating those meta values just like normal tables, while still making
empty elements of those values distinguishable.
