Properties of Block values are marshalled lazily, which generally
improves performance considerably. Script users may also notice the
following differences:
- Block element properties can no longer be accessed by numerical
indexing of the `.c` field. The `.c` property now serves as an alias
for `.content`, so some filter that used this undocumented method
for property access may continue to work, while others will need to
be updated and use proper property names.
- The marshalled Block elements now have a `show` method, and a
`__tostring` metamethod. Both return the Haskell string
representation of the element.
- Block values now have the Lua type `userdata` instead of `table`.
This includes the following user-facing changes:
- Deprecated inline constructors are removed. These are `DoubleQuoted`,
`SingleQuoted`, `DisplayMath`, and `InlineMath`.
- Attr values are no longer normalized when assigned to an Inline
element property.
- It's no longer possible to access parts of Inline elements via
numerical indexes. E.g., `pandoc.Span('test')[2]` used to give
`pandoc.Str 'test'`, but yields `nil` now. This was undocumented
behavior not intended to be used in user scripts. Use named properties
instead.
- Accessing `.c` to get a JSON-like tuple of all components no longer
works. This was undocumented behavior.
- Only known properties can be set on an element value. Trying to set a
different property will now raise an error.
- Adds a new `pandoc.AttributeList()` constructor, which creates the
associative attribute list that is used as the third component of
`Attr` values. Values of this type can often be passed to constructors
instead of `Attr` values.
- `AttributeList` values can no longer be indexed numerically.
A new type `SimpleTable` is made available to Lua filters. It is
similar to the `Table` type in pandoc versions before 2.10;
conversion functions from and to the new Table type are provided.
Old filters using tables now require minimal changes and can use,
e.g.,
if PANDOC_VERSION > {2,10,1} then
pandoc.Table = pandoc.SimpleTable
end
and
function Table (tbl)
tbl = pandoc.utils.to_simple_table(tbl)
…
return pandoc.utils.from_simple_table(tbl)
end
to work with the current pandoc version.
This changes the Lua API. It is highly unlikely for this change to
affect existing filters, since the documentation for the new Table
constructor (and type) was incomplete and partly wrong before.
The Lua API is now more consistent, as all constructors for elements
with attributes now take attributes as the last parameter.
Attr values can now be given as normal Lua tables; this can be used as a
convenient alternative to define Attr values, instead of constructing
values with `pandoc.Attr`. Identifiers are taken from the *id* field,
classes must be given as space separated words in the *class* field. All
remaining fields are included as misc attributes.
With this change, the following lines now create equal elements:
pandoc.Span('test', {id = 'test', class = 'a b', check = 1})
pandoc.Span('test', pandoc.Attr('test', {'a','b'}, {check = 1}))
This also works when using the *attr* setter:
local span = pandoc.Span 'text'
span.attr = {id = 'test', class = 'a b', check = 1}
Furthermore, the *attributes* field of AST elements can now be a plain
key-value table even when using the `attributes` accessor:
local span = pandoc.Span 'test'
span.attributes = {check = 1} -- works as expected now
Closes: #5744
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.
Albert Krewinkel