Merge pull request #5312 from tarleb/pandoc-mediabag-extension

Pandoc mediabag extension

1 files changed, 45 insertions, 1 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 45abe8ac8..2a9646dfd 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -2448,9 +2448,26 @@ The module is loaded as part of module `pandoc` and can either be
 accessed via the `pandoc.mediabag` field, or explicitly required,
 e.g.:
 
-
     local mb = require 'pandoc.mediabag'
 
+### delete {#mediabag-delete}
+
+`delete (filepath)`
+
+Removes a single entry from the media bag.
+
+Parameters:
+
+`filepath`:
+:   filename of the item to be deleted. The media bag will be
+    left unchanged if no entry with the given filename exists.
+
+### empty {#mediabag-empty}
+
+`empty ()`
+
+Clear-out the media bag, deleting all items.
+
 ### insert {#mediabag-insert}
 
 `insert (filepath, mime_type, contents)`
@@ -2475,6 +2492,33 @@ Usage:
     local contents = "Hello, World!"
     pandoc.mediabag(fp, mt, contents)
 
+### iter {#mediabag-iter}
+
+`items ()`
+
+Returns an iterator triple to be used with Lua's generic `for`
+statement. The iterator returns the filepath, MIME type, and
+content of a media bag item on each invocation. Items are
+processed one-by-one to avoid excessive memory use.
+
+This function should be used only when full access to all items,
+including their contents, is required. For all other cases,
+[`list`](#mediabag-list) should be preferred.
+
+Returns:
+
+  - The iterator function; must be called with the iterator state
+    and the current iterator value.
+  - Iterator state – an opaque value to be passed to the iterator
+    function.
+  - Initial iterator value.
+
+Usage:
+
+    for fp, mt, contents in pandoc.mediabag.items() do
+      -- print(fp, mt, contents)
+    end
+
 ### list {#mediabag-list}
 
 `list ()`