path: root/_extensions/ruc-play/semantic-markdown/semantic-markdown.lua

--- semantic-markdown - Pandoc plugin to process semantic hints
---
--- SPDX-FileCopyrightText: 2025  Jonas Smedegaard <dr@jones.dk>
--- SPDX-License-Identifier: GPL-3.0-or-later
---
--- ## Examples
---
--- Ideally, this text:
---
--- ```Markdown+RDF
--- Simple ontological annotation:
--- [This]{foaf:depiction} is not a pipe.
---
--- Nested, mixed-use and custom-namespaced annotations:
--- [[Ceci]{foaf:depiction} n'est pas une pipe.]{lang=fr bibo:Quote}
---
--- {bibo}: http://purl.org/ontology/bibo/
--- ```
---
--- ...should with this filter be transformed to this text:
---
--- ```Markdown
--- ---
--- turtle: |
---   @prefix bibo: http://purl.org/ontology/bibo/
---
---   _:001 a foaf:depiction .
---   _:002 a foaf:depiction .
---   _:003 a bibo:Quote .
--- ---
--- Simple ontological annotation:
--- This is not a pipe.
---
--- Nested, mixed-use and custom-namespaced annotations:
--- [Ceci n'est pas une pipe.]{lang=fr}
--- ```
---
--- When target document format is html,
--- this filter should ideally produce RDFa 1.1 Lite or Core data.
--- (Lite is *not* a subset of Core as it deviates slightly).
---
--- * v0.0.1
---   * initial release
---
--- @version 0.0.1
--- @see <https://source.jones.dk/semantic-markdown/about/>
--- @see <https://moodle.ruc.dk/course/view.php?id=23505>
--- @see <https://www.w3.org/TR/rdfa-primer/#using-rdfa>
--- @see <https://www.ctrl.blog/entry/rdfa-link-attributes.html>

-- TODO: maybe use topdown traversal
--  * order of declaring annotations might matter (but should not)
--  * might enable simpler functions and/or faster processing
-- @see <https://pandoc.org/lua-filters.html#topdown-traversal>

-- ensure stable character classes independent of system locale
-- @see <https://pandoc.org/lua-filters.html#common-pitfalls>
os.setlocale 'C'

-- TODO: cover non-ASCII Unicode characters
-- @see <https://www.lua.org/manual/5.4/manual.html#6.5>
--- Curie_long - CURIE with prefix and reference as set of chars
--- @see <https://www.w3.org/TR/rdfa-core/#h-s_curies>
local _name_start_char = "A-Z_a-z"
local _name_char = _name_start_char.."-0-9"
local _reference = "[".._name_start_char.."][".._name_char.."]*"
local _prefix = "[".._name_start_char.."_-][".._name_char.."]*"
local curie_long = _prefix..":".._reference

--- curie_no_ref - CURIE with only prefix as set of chars
local curie_no_ref = _prefix..":"

--- curie_local - CURIE with only name as set of chars
local curie_local = ":".._reference

--- curie_default - CURIE without prefix or name as char
local curie_default = ":"

-- TODO: curie_re - CURIE as `LPeg.re` regex object
-- TODO: test and replace above curie* patterns
-- @see <https://pandoc.org/lua-filters.html#global-variables>
--local curie_re = re.compile("(".._prefix..")?:(".._reference..")?")

-- FIXME: define RDF context same as RDFa
-- TODO: maybe support overriding context with a JSON-LD URI
-- @see <https://www.w3.org/2011/rdfa-context/rdfa-1.1>

--- Namespaces - process RDF namespace IRI declarations
---
--- Takes as input a list of Para block elements.
--- For each block matching the pattern for a namespace IRI definition,
--- the declared namespace is extracted.
--- Returns an empty paragraph in case of a match,
--- or nothing (to signal preservation of original content).
---
--- Example:
---
--- ```Markdown
--- # Annotated paragraph using a custom namespace
---
--- My favorite animal is the [Liger]{ov:preferredAnimal}.
---
--- {ov}: http://open.vocab.org/terms/
--- ```
---
--- @param blocks  Markdown with ontological annotations as Blocks
--- @returns       Markdown without ontological annotations as Blocks
--- @see <https://pandoc.org/lua-filters.html#type-blocks>
--- @see <https://www.w3.org/TR/rdf12-concepts/#vocabularies>
local function Namespaces(blocks)
  if #blocks.content == 3
    and blocks.content[1].t == "Str"
    and blocks.content[2].t == "Space"
    and blocks.content[3].t == "Str"
    and blocks.content[1].text:match "^{"..curie_no_ref.."}%:%:$"
    and blocks.content[3].text:match "^https?:"
  then
    -- FIXME: register namespace in Meta
    return pandoc.Blocks {}
  end
end

--- Statements - process inline RDF statements
---
--- Track enclosure changes and process relevant embedded statements
--- for each Inlines object in a Pandoc Abstract Syntax Tree (AST).
---
--- ```ASCII-art
--- Simple ontological annotation:
--- "A [map]{foaf:depiction} is not the territory"
---    |   ||              |
---    |   |`brace_begin   `brace_end
---    |   `bracket_end
---    `bracket_begin
---
--- Nested and mixed-use annotations:
--- ["[Ceci]{foaf:depiction} n'est pas une pipe"]{lang=fr dc:Text}
--- | |    ||              |                    ||               |
--- | |    |`brace_begin   `brace_end           |`brace_begin    |
--- | |    `inner_bracket_end                   |           brace_end
--- | `inner_bracket_begin                      `outer_bracket_end
--- `outer_bracket_end
--- ```
---
--- @param inlines  Markdown with semantic annotations as Inlines
--- @returns        Markdown stripped of semantic annotations as Inlines
--- @see <https://pandoc.org/lua-filters.html#type-inline>
function Statements (blocks)

  -- positions of enclosure markers
  local pos_bracket_begin, pos_brace_begin, pos_brace_end

  -- positions of beginning of enclosed content
  -- usable as flags, since it is always preceded by a marker
  local pos_bracketed, pos_braced

  -- amount of detected statements in this block
  local statement_count = 0

  local new_inlines = {}

  for i, el in ipairs(blocks.content) do

    -- only string inlines can alter state
    if el.t ~= 'Str' then
      table.insert(new_inlines, el)
      goto continue
    end

    -- unenclosed
    if not (pos_bracketed or pos_braced) then
      _, pos_bracket_begin = string.find(el.text, "%[")
      if pos_bracket_begin then
        pos_bracketed = pos_bracket_begin + 1
      end
    end

    -- enters a bracket enclosure
    -- TODO: maybe support nested bracket enclosure
    if pos_bracketed and not pos_braced then
      _, pos_brace_begin, s = string.find(el.text, "^([^%[%]}]*)%]{",
        pos_bracketed)
      if pos_brace_begin then
        pos_braced = pos_brace_begin + 1
        table.insert(new_inlines, pandoc.Str(s))
      end
    end

    -- (ignore space-delimited enclosures: not in spec for inlines)

    -- completes a brace enclosure
    -- TODO: support mixed-use enclosure
    -- TODO: cover curie_prefix and curie_local and curie_default
    if pos_braced then
      _, pos_brace_end = string.find(el.text, "^"..curie_long.."}",
        pos_braced)
      if pos_brace_end then
        statement_count = statement_count + 1
        -- TODO: call same function with remains of Str
      end
    end
    ::continue::
  end
-- FIXME
--  if statement_count then
--    return pandoc.Inlines {new_inlines}
--  end
end

-- First resolve namespace declarations, then statements.
--
-- Although this filter is *not* a full RDF parser,
-- order matters for the parts we do handle --
-- e.g. namespace resolving is similar to other RDF formats
-- with detailed documented process ordering.
--
-- @see <https://www.w3.org/TR/turtle/#sec-parsing>
local meta = {}
return {

  -- move aside MetaBlocks to speed up processing content
  --
  -- @see <https://stackoverflow.com/a/47356252/18619283>
  { Meta = function(m) meta = m; return {} end },

  {Para = Namespaces},

  {Block = Statements},

  -- FIXME: add custom declared namespaces in Meta
  -- TODO: maybe add only actively used namespaces
  -- (do same as for unused link definitions)
  { Meta = function(_) return meta; end },
  --{ Meta = function(_) return NamespacesToMeta(meta); end },
}