Merge pull request #416 from li-zyang/feat_api_NERDCommentIsCharCommented

Feature: API 'NERDCommentIsCharCommented(line, col)'

.gitignore

@@ -1,3 +1,4 @@
 *~
 *.swp
 tags
+DEBUG

doc/NERD_commenter.txt

@@ -38,13 +38,14 @@ CONTENTS                                               *NERDCommenterContents*
         4.2 Options details...................|NERDCommenterOptionsDetails|
         4.3 Default delimiter Options.........|NERDCommenterDefaultDelims|
     5. Customising key mappings...............|NERDCommenterMappings|
-    6. Issues with the script.................|NERDCommenterIssues|
+    6. Interfaces............................. NERDCommenterInterfaces
-        6.1 Delimiter detection heuristics....|NERDCommenterHeuristics|
+    7. Issues with the script.................|NERDCommenterIssues|
-        6.2 Nesting issues....................|NERDCommenterNesting|
+        7.1 Delimiter detection heuristics....|NERDCommenterHeuristics|
-    7.About..     ............................|NERDCommenterAbout|
+        7.2 Nesting issues....................|NERDCommenterNesting|
-    8.Changelog...............................|NERDCommenterChangelog|
+    8.About..     ............................|NERDCommenterAbout|
-    9.Credits.................................|NERDCommenterCredits|
+    9.Changelog...............................|NERDCommenterChangelog|
-    10.License................................|NERDCommenterLicense|
+    10.Credits................................|NERDCommenterCredits|
+    11.License................................|NERDCommenterLicense|
 
 ==============================================================================
 1. Intro                                                       *NERDCommenter*
@@ -883,11 +884,46 @@ map to.
 See also |'NERDCreateDefaultMappings'|.
 
 ==============================================================================
-6. Issues with the script                                *NERDCommenterIssues*
+6. Interfaces                                        *NERDCommenterInterfaces*
+
+NERDCommentIsLineCommented({lineNo})            *NERDCommentIsLineCommented()*
+            Check if the line is a comment
+            Note this function checks if the line is **completely** a comment
+            Args:
+              {lineNo}:     the line number of the line to check
+            Return: Number, 1 if the line is a comment, 0 else
+
+
+NERDComment({mode}, {type})                                    *NERDComment()*
+            This function is a Wrapper for the main commenting functions
+
+            Args:
+              {mode}:       character indicating the mode in which the comment
+                            is requested:
+                            'n' for Normal mode, 'x' for Visual mode
+              {type}:       the type of commenting requested. Can be 'Sexy', 
+                            'Invert', 'Minimal', 'Toggle', 'AlignLeft', 
+                            'AlignBoth', 'Comment', 'Nested', 'ToEOL', 'Append',
+                            'Insert', 'Uncomment', 'Yank'
+
+
+NERDCommentIsCharCommented({line}, {col})       *NERDCommentIsCharCommented()*
+            Check if the character at [{line}, {col}] is inside a comment
+            Note the Comment delimeter it self is considered as part of the 
+            comment
+
+            Args:
+              {line}       the line number of the character
+              {col}        the column number of the character
+            Return: Number, 1 if the character is inside a comment, 0 else
+
+
+==============================================================================
+7. Issues with the script                                *NERDCommenterIssues*
 
 
 ------------------------------------------------------------------------------
-6.1 Delimiter detection heuristics                   *NERDCommenterHeuristics*
+7.1 Delimiter detection heuristics                   *NERDCommenterHeuristics*
 
 Heuristics are used to distinguish the real comment delimiters
 
@@ -907,7 +943,7 @@ string. These heuristics, while usually pretty accurate, will not work for all
 cases.
 
 ------------------------------------------------------------------------------
-6.2 Nesting issues                                      *NERDCommenterNesting*
+7.2 Nesting issues                                      *NERDCommenterNesting*
 
 If we have some line of code like this: >
     /*int foo */ = /*5 + 9;*/
@@ -927,7 +963,7 @@ will become: >
 for simplicity)
 
 ==============================================================================
-7. About                                                  *NERDCommenterAbout*
+8. About                                                  *NERDCommenterAbout*
 
 The author of the NERD commenter is Martyzillatron --- the half robot, half
 dinosaur bastard son of Megatron and Godzilla. He enjoys destroying
@@ -944,7 +980,7 @@ The latest dev versions are on github
     http://github.com/preservim/nerdcommenter
 
 ==============================================================================
-8. Changelog                                          *NERDCommenterChangelog*
+9. Changelog                                          *NERDCommenterChangelog*
 
 2.3.0
     - remove all filetypes which have a &commentstring in the standard vim
@@ -1010,7 +1046,7 @@ The latest dev versions are on github
       NERDCommenterInsert if you wish to restore it
 
 ==============================================================================
-9. Credits                                              *NERDCommenterCredits*
+10. Credits                                              *NERDCommenterCredits*
 
 Thanks to the follow people for suggestions and patches:
 
@@ -1149,7 +1185,7 @@ Ivan Devat                          javascript.jquery
 tpope                               cucumber,pdf
 Lyude Paul                          piglit shader_test
 ==============================================================================
-10. License                                             *NERDCommenterLicense*
+11. License                                             *NERDCommenterLicense*
 
 The NERD commenter is released under the wtfpl.
 See http://sam.zoy.org/wtfpl/COPYING.

plugin/NERD_commenter.vim

@@ -1209,6 +1209,12 @@ function s:InvertComment(firstLine, lastLine)
     endwhile
 endfunction
 
+" Function: NERDCommentIsLineCommented(lineNo)
+" Check if the line is a comment
+" Note this function checks if the line is **completely** a comment
+" Args:
+"   -lineNo:    the line number of the line to check
+" Return: Number, 1 if the line is a comment, 0 else
 function! NERDCommentIsLineCommented(lineNo)
     let theLine = getline(a:lineNo)
     return s:IsInSexyComment(a:lineNo) || s:IsCommentedFromStartOfLine(s:Left(), theLine) || s:IsCommentedFromStartOfLine(s:Left({'alt': 1}), theLine)
@@ -1356,6 +1362,117 @@ function! NERDComment(mode, type) range
 
 endfunction
 
+" Function: NERDCommentIsCharCommented(line, col) abort
+" Check if the character at [line, col] is inside a comment
+" Note the Comment delimeter it self is considered as part of the comment
+" 
+" Args:
+"   -line       the line number of the character
+"   -col        the column number of the character
+" Return: Number, 1 if the character is inside a comment, 0 if is not
+function! NERDCommentIsCharCommented(line, col) abort
+  " Function: s:searchfor(str, line, col, direction, [maxline])
+  " search str in the buffer, including the character at [line, col]
+  " Args: 
+  "   -str:       the string for search
+  "   -line:      the line number where search begins
+  "   -col:       the column number where search begins
+  "   -direction: 0 if forward, and 1 if backward
+  "   -maxline:   the max lines the search would look up
+  "               1 if search only one line
+  "               if not given, search until reaches the begining or end of file
+  " Return: List, in the format of [line, col], where line and col is the
+  "         position of first found result; If str cannot be found, returns
+  "         [0, 0]
+  function! s:searchfor(str, line, col, direction, ...) abort
+    let l:curlinenr = a:line
+    let l:maxline = (a:0 > 0) ? a:1 : (a:direction ? a:line : line('$') - a:line + 1)
+    while abs(curlinenr - a:line) < maxline
+      let linestr = getline(curlinenr)
+      if curlinenr == a:line
+        if !a:direction
+          let l:partstr = strpart(linestr, a:col - strlen(a:str))
+        else
+          let l:partstr = strpart(linestr, 0, a:col + strlen(a:str) - 1)
+        endif
+      else
+        let l:partstr = linestr
+      endif
+      if !a:direction
+        " forward
+        let idx = stridx(partstr, a:str)
+        if idx != -1
+          if curlinenr == a:line
+            let idx += a:col - strlen(a:str)
+          else
+          endif
+          return [curlinenr, idx + 1]
+        endif
+      else
+        " backward
+        let idx = strridx(partstr, a:str)
+        if idx != -1
+          return [curlinenr, idx + 1]
+        endif
+      endif
+      let curlinenr += a:direction ? -1 : 1
+    endwhile
+    return [0, 0]
+  endfunction
+  " Function: s:checkwith(left, right, line, col) abort
+  " check if the char at [line, col] is commented using [left, right] pair
+  " Args:
+  "   -left:      the string begins a comment
+  "   -right:     the string ends a comment
+  "   -line:      the line position of the character
+  "   -col:       the column position of the character
+  " Return: Number, 1 if is in a comment, 0 else
+  function! s:checkwith(left, right, line, col) abort
+    let linecommented  = 0
+    let blockcommented = 0
+    if a:right ==# ''
+      let leftpos = s:searchfor(a:left, a:line, a:col, 1, 1)
+      if leftpos == [0, 0]
+        if !linecommented | let linecommented = 0 | endif
+      else
+        if !linecommented | let linecommented = 1 | endif
+      endif
+    else
+      let leftpos = s:searchfor(a:left, a:line, a:col, 1)
+      if leftpos == [0, 0]
+        if !blockcommented | let blockcommented = 0 | endif
+      else 
+        " call s:searchfor(a:right, a:line, a:col, 0)
+        let rightpos = s:searchfor(a:right, leftpos[0], leftpos[1] + strlen(a:right) + 1, 0)
+        if rightpos != [0, 0]
+          if rightpos[0] < a:line
+            if !blockcommented | let blockcommented = 0 | endif
+          elseif rightpos[0] == a:line
+            if !blockcommented 
+              let blockcommented = (rightpos[1] + strlen(a:right) > a:col) ? 1 : 0
+            endif
+          else " rightpos > a:line
+            if !blockcommented | let blockcommented = 1 | endif
+          endif
+        else
+          if !blockcommented | let blockcommented = 1 | endif
+        endif
+      endif
+    endif
+    return linecommented || blockcommented
+  endfunction
+  return s:checkwith(
+          \ b:NERDCommenterDelims['left'], 
+          \ b:NERDCommenterDelims['right'], 
+          \ a:line, 
+          \ a:col) || 
+        \ s:checkwith(
+          \ b:NERDCommenterDelims['leftAlt'], 
+          \ b:NERDCommenterDelims['rightAlt'], 
+          \ a:line, 
+          \ a:col)
+endfunction
+
 " Function: s:PlaceDelimitersAndInsBetween() function {{{2
 " This is function is called to place comment delimiters down and place the
 " cursor between them