change.txt

diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index 5bebc3a..28102f1 100644
--- a/ldoc/parse.lua
+++ b/ldoc/parse.lua
@@ -6,6 +6,21 @@ local tools = require 'ldoc.tools'
 local doc = require 'ldoc.doc'
 local Item,File = doc.Item,doc.File
 
+-- This functionality is only needed for UML support.
+-- If this does not load it will only trigger a failure
+-- if the UML syntax was detected.
+local bOk, http   = pcall( require, "socket.http")
+local mime        = nil
+if bOk == false then
+   http = nil
+else
+   bOk, mime   = pcall( require, "mime")
+   if bOk == false then
+      mime = nil
+   end
+end
+
+
 ------ Parsing the Source --------------
 -- This uses the lexer from PL, but it should be possible to use Peter Odding's
 -- excellent Lpeg based lexer instead.
@@ -46,6 +61,138 @@ function parse_tags(text)
    return preamble,tag_items
 end
 
+-- Used to preprocess the tag text prior to extracting
+-- tags.  This allows us to replace tags with other text.
+-- For example, we embed images into the document.
+local function preprocess_tag_strings( s )
+
+   local function create_embedded_image( filename, fileType )
+
+      local html = ""
+
+      if mime == nil then
+         local errStr = "LDoc error, Lua socket/mime module needed for UML"
+         -- Just log the error in the doc
+         html = "<b><u>"..errStr.."</u></b>"
+         print(errStr)
+         return html
+      end
+
+      if fileType == nil then
+         fileType = "png"
+      end
+
+      -- Now open the new image file and embed it
+      -- into the text as an HTML image
+      local fp = io.open( filename, "r" )
+      if fp then
+         -- This could be more efficient instead of
+         -- reading all since the definitions are
+         -- typically small this will work for now
+         local img = fp:read("*all")
+         fp:close()
+
+         html = string.format( '<img src="data:image/%s;base64,%s" />', fileType, mime.b64( img ) )
+      else
+         local errStr = string.format("LDoc error opening %s image file: %q", fileType, filename)
+         -- Just log the error in the doc
+         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
+         print(errStr)
+      end
+
+      return html
+   end
+
+   ----------------------------------------------------------
+   -- Embedded UML
+   ------------------
+   local epos
+   local execPath = "plantuml %s"
+   local spos     = string.find(s, "@startuml")
+   if spos then
+      _, epos = string.find(s, "@enduml")
+   end
+
+   if spos and epos then
+
+      local filename = os.tmpname()
+      local sUml     = string.sub(s,spos,epos) -- UML definition text
+
+      -- Grab the text before and after the UML definition
+      local preStr   = string.match(s, "(.*)@startuml")
+      local postStr  = string.match(s, "@enduml(.*)")
+      local fileType = "png"
+      local fp       = io.open( filename, "w" )
+      local html     = ""
+
+      --Add support for optional formatting in a json format
+      if string.sub( sUml, 10,10 ) == "{" then
+         local sFmt = string.match( sUml, ".*{(.*)}" )
+
+         -- Remove the formatter
+         sUml = string.gsub( sUml, ".*}", "@startuml" )
+
+         -- To avoid adding the dependency of JSON we will
+         -- parse what we need.
+
+         -- "exec":"path"
+         -- This allows you to alter the UML generation engine and path for execution
+         execPath = string.match(sFmt, '.-"exec"%s-:%s-"(.*)".-') or execPath
+
+         -- "removeTags":true
+         -- if true, the @startuml and @enduml are removed, this
+         -- makes it possible to support other UML parsers.
+         sRemoveTags = string.match(sFmt, '.-"removeTags"%s-:%s-(%a*).-')
+         if sRemoveTags == "true" then
+            sUml = string.gsub( sUml, "^%s*@startuml", "" )
+            sUml = string.gsub( sUml, "@enduml%s*$", "" )
+         end
+
+         -- "fileType":"gif"
+         -- This defines a different file type that is generated by
+         -- the UML parsers.
+         fileType = string.match(sFmt, '.-"fileType"%s-:%s-"(.*)".-') or fileType
+      end
+
+      if fp then
+         -- write the UML text to a file
+         fp:write( sUml )
+         fp:close()
+
+         -- create the diagram, overwrites the existing file
+         os.execute( string.format(execPath, filename ) )
+
+         -- create the embedded text for the image
+         html = create_embedded_image( filename, fileType )
+
+         os.remove( filename ) -- this is the PNG from plantUml
+      else
+         local errStr = "LDoc error creating UML temp file"
+         -- Just log the error in the doc
+         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
+         print(errStr)
+      end
+      s = preStr..html..postStr
+
+   end -- embed UML
+
+   ----------------------------------------------------------
+   -- Embedded Image
+   ------------------
+   local fileType, filename = string.match(s, '@embed_(.*){"(.*)"}')
+   if fileType and filename then
+
+      -- create the embedded text for the image
+      html = create_embedded_image( filename, fileType )
+
+      s = string.gsub(s, "@embed_.*{.*}", html)
+
+   end -- embedded image
+
+   return s
+
+end -- preprocess_tag_strings
+
 -- This takes the collected comment block, and uses the docstyle to
 -- extract tags and values.  Assume that the summary ends in a period or a question
 -- mark, and everything else in the preamble is the description.
@@ -53,6 +200,9 @@ end
 -- Alias substitution and @TYPE NAME shortcutting is handled by Item.check_tag
 local function extract_tags (s)
    if s:match '^%s*$' then return {} end
+
+   s = preprocess_tag_strings( s )
+
    local preamble,tag_items = parse_tags(s)
    local strip = tools.strip
    local summary, description = preamble:match('^(.-[%.?])(%s.+)')