computable-pandoc/src/literate.lua

---------------------------------- LITERATE ----------------------------------

-- Stores all literate stuff
local lit = {}

-- Indicates status
lit.status = true

-- Stores literate functions
lit.fns = {}

-- Returns specific grammar
function lit.g(name)
  -- Stores all grammars
  local grammars = {}

  -- Shortcuts
  local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt =
    lpeg.P,
    lpeg.S,
    lpeg.R,
    lpeg.Cf,
    lpeg.Cc,
    lpeg.Ct,
    lpeg.V,
    lpeg.Cs,
    lpeg.Cg,
    lpeg.Cb,
    lpeg.B,
    lpeg.C,
    lpeg.Cmt

  -- Lexical elements
  local newline = P("\r") ^ -1 * P("\n")
  local space = S(" \t")
  local anyspace = S(" \t\r\n")
  local spot = (1 - anyspace)
  local any = (spot + space)
  local yamlheader = space ^ 0 * P("---") * space ^ 0 * newline
  local yamlfooter = space ^ 0 * P("...") * space ^ 0 * newline ^ -1
  local yamlbody = -yamlfooter * any ^ 0 * newline
  local label = R("az", "AZ") * R("az", "AZ", "09", "__") ^ 0
  local ref = -B("\\") * P("#") * C(label)
  local notref = (1 - ref) ^ 0

  -- Function declaration grammar
  grammars["declaration"] = P({
    "Declaration",
    Declaration = Ct(V("YAML") * V("Code"), "name"),
    YAML = C(yamlheader * yamlbody ^ 0 * yamlfooter),
    Code = C((any + newline) ^ 0),
  })

  -- Argument references grammar
  grammars["references"] = notref
    * P({
      "References",
      References = Ct((ref * notref) ^ 0),
    })
    * -1

  return grammars[name]
end

-- Prints located messages
function lit.puts(yaml_key, ...)
  -- Returns debug level as number
  local function debuglevel(str)
    if str == "ERROR" then
      lit.status = false
      return 2
    elseif str == "WARNING" then
      return 1
    else
      return 0
    end
  end

  -- Gets located message
  local function getmsg(key, ...)
    local msg = pandoc.metatotable(pandoc.read([[`locale()`]]).meta)
    local levelname, level, lang = "INFO", 0, os.lang()
    for mtype, msgs in pairs(msg) do
      if msgs[key] then
        key = (msgs[key][lang] ~= nil and msgs[key][lang] or msgs[key]["en"])
        for i, str in ipairs({ ... }) do
          key = key:gsub("#" .. i, str)
        end
        levelname, level = mtype, debuglevel(mtype)
        break
      end
    end
    return key, levelname, level
  end

  local verbosity = debuglevel(PANDOC_STATE.verbosity)
  local msg, levelname, level = getmsg(yaml_key, ...)
  if level >= verbosity then print("[" .. levelname .. "] [LIT] " .. msg) end
end

-- Parses and evaluates literate functions in document
function lit.exam(doc)
  -- Extracts function declarations
  local function extract(codeblock)
    -- Checks function declarations
    local function check(match)
      -- Stores valid declaration
      local declaration = {}

      -- Valid metadata structure
      local metastruct = {
        ["mandatory"] = {
          -- Value as table == whole patterns to match
          ["id"] = { "%a[_%w]*" },
        },
        ["optional"] = {
          ["lang"] = {
            "lua",
            "fennel",
            "python",
            "js",
            "ruby",
            "lisp",
            "graphviz",
          },
          ["cmd"] = { ".+" },
          -- Value as string == type to match
          ["args"] = "table",
          ["shift"] = "boolean",
          ["wipe"] = "boolean",
          ["typed"] = "boolean",
          ["link"] = "path",
          ["img"] = "path",
          ["alt"] = "string",
          ["dump"] = "path",
          ["quote"] = "boolean",
        },
      }

      -- Language commands
      -- Eachs command is a table of table;
      -- First table indicates one or more internal or external evaluations
      -- Second table indicates one or more commands to try
      local langcmds = {
        ["lua"] = { ["int_eval"] = { "CMD1", "CMD2" } },
        ["fennel"] = { ["int_eval"] = { "CMD1", "CMD2" } },
        ["python"] = { ["ext_eval"] = { "CMD1", "CMD2" } },
        ["js"] = { ["ext_eval"] = { "CMD1", "CMD2" } },
        ["ruby"] = { ["ext_eval"] = { "CMD1", "CMD2" } },
        ["lisp"] = { ["ext_eval"] = { "CMD1", "CMD2" } },
        ["graphviz"] = { ["ext_eval"] = { "CMD1", "CMD2" } },
      }

      -- Prints error
      -- Since error messages debuglevel are "ERROR", lit.status turns false
      -- Flush the declaration to avoid storage in lit.fns
      local function putserr(...)
        lit.puts(...)
        declaration = {}
      end

      -- Adds 'eval' key in declaration
      -- This key indicates what to eval
      local function addeval()
        declaration["eval"] = {}
        -- If lang and cmd are present, ignores lang and use cmd as eval
        if declaration["lang"] and declaration["cmd"] then
          lit.puts("ignore_lang", declaration["cmd"], declaration["lang"])
          declaration["eval"] = { ["ext_eval"] = { declaration["cmd"] } }
        -- If neither lang or cmd are presents, defaults lang and eval to lua
        elseif not declaration["lang"] and not declaration["cmd"] then
          declaration["lang"] = "lua"
          declaration["eval"] = langcmds["lua"]
        -- If only lang present, eval is lang
        elseif declaration["lang"] and not declaration["cmd"] then
          declaration["eval"] = langcmds[declaration["lang"]]
        -- If only cmd present, eval is cmd
        elseif not declaration["lang"] and declaration["cmd"] then
          declaration["eval"] = { ["ext_eval"] = { declaration["cmd"] } }
        end
      end

      -- Checks for valid command for Unix systems
      local function checkcmd()
        if declaration["cmd"] then
          local cmd = declaration["cmd"]:split()[1]
          if os.isunix() then
            local status = io.try("type", cmd)
            if not status then putserr("invalid_cmd", cmd) end
          else
            lit.puts("skip_check", "checkcmd")
          end
        end
      end

      -- Checks for extra, unwanted and wrong metadata
      local function checkextra()
        for key, _ in pairs(declaration) do
          local missing1 = metastruct["mandatory"][key] == nil
          local missing2 = metastruct["optional"][key] == nil
          if missing1 and missing2 then putserr("invalid_key", key) end
        end
      end

      -- Checks for valid metadata
      local function checkmeta(kind)
        -- Checks for valid metadata type
        local function checktype(type1, key)
          local val = declaration[key]
          local type2 = type(val)
          if type1 ~= type2 then
            if type1 == "path" then
              if not (pandoc.path.directory(val):isdir()) then
                putserr("invalid_path", val, key)
              end
            else
              putserr("invalid_type", type2, key)
            end
          end
        end

        -- Checks for valid metadata pattern
        local function checkpattern(table, key)
          local val = tostring(declaration[key])
          local err = key
          for _, pattern in pairs(table) do
            if val:match("^" .. pattern .. "$") then
              err = ""
              break
            end
          end
          if not (err:isempty()) then putserr("invalid_value", val, err) end
        end

        for key, val in pairs(metastruct[kind]) do
          if declaration[key] == nil and kind == "mandatory" then
            putserr("no_key", key)
          elseif declaration[key] and type(val) == "table" then
            checkpattern(val, key)
          elseif declaration[key] then
            checktype(val, key)
          end
        end
      end

      -- Parses metadata
      local function parsemeta(yaml)
        local isok, res = pcall(pandoc.read, yaml)
        if isok and not (pandoc.utils.stringify(res.meta):isempty()) then
          declaration = pandoc.metatotable(res.meta)
          checkmeta("mandatory")
          checkmeta("optional")
          checkextra()
          checkcmd()
          if next(declaration) then addeval() end
        elseif isok and pandoc.utils.stringify(res.meta):isempty() then
          putserr("meta_empty")
        else
          putserr("meta_invalid")
        end
      end

      -- TODO
      -- Parses code
      local function parsecode(rawcode)
        local code = ""
        local references = lpeg.match(lit.g("references"), rawcode)
        if references then
          for _, ref in ipairs(references) do
            print("reference:", ref)
          end
        end
        declaration["code"] = code
      end

      if match then
        lit.puts("checking", table.concat(match, ""):indent())
        parsemeta(match[1])
        if next(declaration) then parsecode(match[2]) end
      end
      return declaration
    end

    local parsed = check(lpeg.match(lit.g("declaration"), codeblock.text))
    if next(parsed) then
      -- TODO:
      -- Eval parsed lit.fns and modify code block accordingly
      lit.fns[parsed["id"]] = parsed
    end
    return codeblock
  end

  -- Calls literate functions
  local function call(el)
    -- TODO
    -- Calls literate functions in code inlines
    local function codecall(code)
      return pandoc.Str("EVAL: " .. pandoc.utils.stringify(code))
    end

    local function metacall(meta)
      local function inlinescall(inlines)
        return inlines:walk({
          Code = function(code) return codecall(code) end,
        })
      end

      for key, val in pairs(meta) do
        if pandoc.utils.type(val) == "Inlines" then
          meta[key] = inlinescall(val)
        elseif pandoc.utils.type(val) == "List" then
          for i, item in ipairs(val) do
            if pandoc.utils.type(item) == "Inlines" then
              meta[key][i] = inlinescall(item)
            end
          end
        end
      end
      return meta
    end

    if pandoc.utils.type(el) == "Meta" then
      return metacall(el)
    else
      return codecall(el)
    end
  end

  -- Asserts literate status
  local function assert()
    if not lit.status then
      lit.puts("aborted")
      os.exit(1)
    end
  end

  doc = doc:walk({ CodeBlock = function(block) return extract(block) end })
  doc = doc:walk({ Meta = function(meta) return call(meta) end })
  doc = doc:walk({ Code = function(code) return call(code) end })
  return doc:walk({ Pandoc = function(_) assert() end })
end