Merge pull request #58 from jchristgit/add-new-documentation-features

Update Erlang syntax for recent language changes

Author: hcs42

syntax/erlang.vim

@@ -37,6 +37,80 @@ endif
 let s:cpo_save = &cpo
 set cpo&vim
 
+" "g:erlang_old_style_highlight": Whether to use old style highlighting.
+"
+" *   "g:erlang_old_style_highlight == 0" (default): Use new style
+"     highlighting.
+"
+" *   "g:erlang_old_style_highlight == 1": Use old style highlighting.
+let s:old_style = (exists("g:erlang_old_style_highlight") &&
+                  \g:erlang_old_style_highlight == 1)
+
+" "g:erlang_use_markdown_for_docs": Whether to use Markdown highlighting in
+" docstrings.
+"
+" *   "g:erlang_use_markdown_for_docs == 1": Enable Markdown highlighting in
+"     docstrings.
+"
+" *   "g:erlang_use_markdown_for_docs == 0" (default): Disable Markdown
+"     highlighting in docstrings.
+if exists("g:erlang_use_markdown_for_docs")
+  let s:use_markdown = g:erlang_use_markdown_for_docs
+else
+  let s:use_markdown = 0
+endif
+
+" "g:erlang_docstring_default_highlight": How to highlight the text inside
+" docstrings (except the text which is highlighted by Markdown).
+"
+" If "g:erlang_use_markdown_for_docs == 1":
+"
+" *   "g:erlang_docstring_default_highlight == 'Comment'" (default): the plugin
+"     highlights the plain text inside Markdown as Markdown normally does,
+"     with comment highlighting to regular text in the docstring.
+"
+" *   If you set g:erlang_docstring_default_highlight to the name of highlight
+"     group, for example "String", the plugin highlights the plain text inside
+"     Markdown with the specified highlight group. See ":highlight" for the
+"     available groups. You may also set it to an empty string to disable any
+"     specific highlighting.
+"
+" If "g:erlang_use_markdown_for_docs == 0":
+"
+" *   "g:erlang_docstring_default_highlight == 'Comment'" (default): the plugin
+"     does not highlight the contents of the docstring as markdown, but
+"     continues to display them in the style of comments.
+"
+" *   If you set g:erlang_docstring_default_highlight to the name of highlight
+"     group, for example "String", the plugin highlights the plain text inside
+"     Markdown with the specified highlight group. See ":highlight" for the
+"     available groups. You may also set it to an empty string to disable any
+"     specific highlighting.
+"
+" Configuration examples:
+"
+"    " Highlight docstrings as Markdown.
+"    let g:erlang_use_markdown_for_docs = 1
+"    let g:erlang_docstring_default_highlight = 'Comment'
+"
+"    " 1. Highlight Markdown elements in docstrings as Markdown.
+"    " 2. Highlight the plain text in docstrings as String.
+"    let g:erlang_use_markdown_for_docs = 1
+"    let g:erlang_docstring_default_highlight = 'String'
+"
+"    " Highlight docstrings as strings.
+"    let g:erlang_use_markdown_for_docs = 0
+"    let g:erlang_docstring_default_highlight = 'String'
+"
+"    " Highlight docstrings as comments (default).
+"    let g:erlang_use_markdown_for_docs = 0
+"    let g:erlang_docstring_default_highlight = 'Comment'
+if exists("g:erlang_docstring_default_highlight")
+  let s:docstring_default_highlight = g:erlang_docstring_default_highlight
+else
+  let s:docstring_default_highlight = 'Comment'
+endif
+
 " Case sensitive
 syn case match
 
@@ -55,6 +129,21 @@ syn match erlangNumberFloat   '\<\d\+\.\d\+\%([eE][+-]\=\d\+\)\=\>'
 
 " Strings, atoms, characters
 syn region erlangString            start=/"/ end=/"/ contains=erlangStringModifier
+syn region erlangStringTripleQuoted matchgroup=String start=/"""/ end=/\%(^\s*\)\@<="""/ keepend
+
+" Documentation
+syn region erlangDocString          start=/^-\%(module\)\=doc\s*\~\="""/ end=/\%(^\s*\)\@<="""\.$/ contains=@erlangDocStringCluster keepend
+syn region erlangDocString          start=/^-\%(module\)\=doc\s*<<"""/ end=/\%(^\s*\)\@<=""">>\.$/ contains=@erlangDocStringCluster keepend
+syn region erlangDocString          start=/^-\%(module\)\=doc\s*\~\="/ end=/"\.$/                  contains=@erlangDocStringCluster keepend
+syn region erlangDocString          start=/^-\%(module\)\=doc\s*<<"/ end=/">>\.$/                  contains=@erlangDocStringCluster keepend
+syn cluster erlangDocStringCluster contains=erlangInnerDocAttribute,erlangDocStringDelimiter
+syn region erlangDocStringDelimiter matchgroup=erlangString start=/"/ end=/"/ contains=@erlangDocStringContained contained
+syn region erlangDocStringDelimiter matchgroup=erlangString start=/"""/ end=/"""/ contains=@erlangDocStringContained contained
+
+if s:use_markdown
+  syn cluster erlangDocStringContained contains=@markdown
+endif
+
 syn region erlangQuotedAtom        start=/'/ end=/'/ contains=erlangQuotedAtomModifier
 syn match erlangStringModifier     '\\\%(\o\{1,3}\|x\x\x\|x{\x\+}\|\^.\|.\)\|\~\%([ni~]\|\%(-\=\d\+\|\*\)\=\.\=\%(\*\|\d\+\)\=\%(\..\)\=[tl]*[cfegswpWPBX#bx+]\)' contained
 syn match erlangQuotedAtomModifier '\\\%(\o\{1,3}\|x\x\x\|x{\x\+}\|\^.\|.\)' contained
@@ -94,12 +183,14 @@ syn match erlangBitType '\%(\/\%(\s\|\n\|%.*\n\)*\)\@<=\%(integer\|float\|binary
 
 " Constants and Directives
 syn match erlangUnknownAttribute '^\s*-\%(\s\|\n\|%.*\n\)*\l[[:alnum:]_@]*' contains=erlangComment
-syn match erlangAttribute '^\s*-\%(\s\|\n\|%.*\n\)*\%(behaviou\=r\|compile\|export\(_type\)\=\|file\|import\|module\|author\|copyright\|doc\|vsn\|on_load\|optional_callbacks\|feature\|mode\)\>' contains=erlangComment
+syn match erlangAttribute '^\s*-\%(\s\|\n\|%.*\n\)*\%(behaviou\=r\|compile\|dialyzer\|export\|export_type\|file\|import\|module\|author\|copyright\|vsn\|on_load\|optional_callbacks\|feature\|mode\)\>' contains=erlangComment
+syn match erlangDocAttribute '^\s*-\%(\s\|\n\|%.*\n\)*\%(moduledoc\|doc\)\>' contains=erlangComment,erlangDocString
+syn match erlangInnerDocAttribute '^\s*-\%(\s\|\n\|%.*\n\)*\%(moduledoc\|doc\)\>' contained
 syn match erlangInclude   '^\s*-\%(\s\|\n\|%.*\n\)*\%(include\|include_lib\)\>' contains=erlangComment
 syn match erlangRecordDef '^\s*-\%(\s\|\n\|%.*\n\)*record\>' contains=erlangComment
 syn match erlangDefine    '^\s*-\%(\s\|\n\|%.*\n\)*\%(define\|undef\)\>' contains=erlangComment
 syn match erlangPreCondit '^\s*-\%(\s\|\n\|%.*\n\)*\%(ifdef\|ifndef\|else\|endif\)\>' contains=erlangComment
-syn match erlangType      '^\s*-\%(\s\|\n\|%.*\n\)*\%(spec\|type\|opaque\|callback\)\>' contains=erlangComment
+syn match erlangType      '^\s*-\%(\s\|\n\|%.*\n\)*\%(spec\|type\|opaque\|nominal\|callback\)\>' contains=erlangComment
 
 " Keywords
 syn keyword erlangKeyword after begin case catch cond end fun if let of else
@@ -147,9 +238,21 @@ let b:erlang_syntax_synced = 1
 " Define the default highlighting. See ":help group-name" for the groups and
 " their colors.
 
-let s:old_style = (exists("g:erlang_old_style_highlight") &&
-                  \g:erlang_old_style_highlight == 1)
+if s:use_markdown
+  " Add markdown syntax elements for docstrings (actually, for all
+  " triple-quoted strings).
+  unlet! b:current_syntax
 
+  syn include @markdown syntax/markdown.vim
+  let b:current_syntax = "erlang"
+
+  " markdown-erlang.vim includes html.vim, which includes css.vim, which adds
+  " the dash character (-) to the list of syntax keywords, which causes
+  " `-VarName` not to be highlighted as a variable in the Erlang code.
+  "
+  " Here we override that.
+  syntax iskeyword @,48-57,192-255,$,_
+endif
 
 " Comments
 hi def link erlangComment Comment
@@ -163,6 +266,12 @@ hi def link erlangNumberFloat Float
 
 " Strings, atoms, characters
 hi def link erlangString String
+hi def link erlangStringTripleQuoted String
+
+" Triple quoted strings
+if s:docstring_default_highlight != ''
+  execute 'hi def link erlangDocStringDelimiter '. s:docstring_default_highlight
+endif
 
 if s:old_style
 hi def link erlangQuotedAtom Type
@@ -232,6 +341,8 @@ hi def link erlangPreCondit Type
 hi def link erlangType Type
 else
 hi def link erlangAttribute Keyword
+hi def link erlangDocAttribute Keyword
+hi def link erlangInnerDocAttribute Keyword
 hi def link erlangMacroDef Macro
 hi def link erlangUnknownAttribute Normal
 hi def link erlangInclude Include