Merge pull request #185 from mooffie/user_keywords

Support used-defined keywords (in prettified code).

doc/doc.md

@@ -1275,6 +1275,9 @@ function tagged with a certain tag:
   - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
   - `template_escape` overrides the usual '#' used for Lua code in templates.
 This needs to be changed if the output format is Markdown, for instance.
+  - `user_keywords` A list of keywords that will be marked in "prettified" code. Useful if
+you want to display your own functions in a special way. Each keyword may be styled differently
+(using CSS). Only works when `pretty` is set to 'lua' (the default).
 
 _Available functions are:_
 

ldoc.lua

@@ -233,7 +233,7 @@ local ldoc_contents = {
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
    'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
    'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references',
-   'dont_escape_underscore','global_lookup','prettify_files','convert_opt'
+   'dont_escape_underscore','global_lookup','prettify_files','convert_opt', 'user_keywords',
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
 
@@ -504,7 +504,7 @@ end
 -- (this also will initialize the code prettifier used)
 override ('format','plain')
 override 'pretty'
-ldoc.markup = markup.create(ldoc, args.format,args.pretty)
+ldoc.markup = markup.create(ldoc, args.format, args.pretty, ldoc.user_keywords)
 
 ------ 'Special' Project-level entities ---------------------------------------
 -- Examples and Topics do not contain code to be processed for doc comments.

ldoc/html/ldoc_css.lua

@@ -304,6 +304,7 @@ pre .number { color: #f8660d; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
 pre .global { color: #800080; }
+pre .user-keyword { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 ]==]

ldoc/html/ldoc_fixed_css.lua

@@ -312,6 +312,7 @@ pre .number { color: #f8660d; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
 pre .global { color: #800080; }
+pre .user-keyword { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 ]]

ldoc/html/ldoc_one_css.lua

@@ -280,6 +280,7 @@ pre .number { color: #f8660d; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
 pre .global { color: #800080; }
+pre .user-keyword { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 ]==]

ldoc/html/ldoc_pale_css.lua

@@ -303,6 +303,7 @@ pre .number { color: #f8660d; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
 pre .global { color: #800080; }
+pre .user-keyword { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 ]]

ldoc/markup.lua

@@ -319,7 +319,7 @@ local function get_processor(ldoc, format)
 end
 
 
-function markup.create (ldoc, format, pretty)
+function markup.create (ldoc, format, pretty, user_keywords)
    local processor
    markup.plain = true
    if format == 'backtick' then
@@ -329,6 +329,7 @@ function markup.create (ldoc, format, pretty)
    backtick_references = ldoc.backtick_references
    global_context = ldoc.package and ldoc.package .. '.'
    prettify.set_prettifier(pretty)
+   prettify.set_user_keywords(user_keywords)
 
    markup.process_reference = function(name,istype)
       if local_context == 'none.' and not name:match '%.' then

ldoc/prettify.lua

@@ -4,9 +4,12 @@
 -- A module reference to an example `test-fun.lua` would look like
 -- `@{example:test-fun}`.
 local List = require 'pl.List'
+local tablex = require 'pl.tablex'
 local globals = require 'ldoc.builtin.globals'
 local prettify = {}
 
+local user_keywords = {}
+
 local escaped_chars = {
    ['&'] = '&',
    ['<'] = '&lt;',
@@ -58,7 +61,9 @@ function prettify.lua (lang, fname, code, initial_lineno, pre, linenos)
       if globals.functions[val] or globals.tables[val] then
          t = 'global'
       end
-      if spans[t] then
+      if user_keywords[val] then
+        res:append(span('user-keyword keyword-' .. val,val))
+      elseif spans[t] then
          if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..`
             val = prettify.resolve_inline_references(val,error_reporter)
          end
@@ -111,5 +116,11 @@ function prettify.set_prettifier (pretty)
    end
 end
 
+function prettify.set_user_keywords(keywords)
+  if keywords then
+    user_keywords = tablex.makeset(keywords)
+  end
+end
+
 return prettify