Help: Fix lexing of multi-line strings

Teach our CMake lexer to recognize `[[...]]` multi-line strings, as used
in some 'check source compiles/runs' examples to pass literal C/C++ code
through a CMake function. Previously, this resulted in the lexer trying
to parse such code as CMake, which is obviously incorrect. Also, use the
new `[[` syntax in more places.

Note that, because `[[...]]` can also show up in some instances denoting
optional arguments, we only consider `[[` with no `=` as a string if the
`[[` is followed by a non-identifier character. This heuristic seems to
work for most existing usages.

Co-Authored-By: Georg Brandl <[email protected]>

CONTRIBUTORS.rst

@@ -28,6 +28,7 @@ The following individuals and institutions are among the contributors:
 * `Eran Ifrah <mailto:[email protected]>`_
 * Esben Mose Hansen, Ange Optimization ApS
 * `Geoffrey Viola <mailto:[email protected]>`_
+* `Georg Brandl <mailto:[email protected]>`_
 * `Google Inc <https://www.google.com/>`_
 * Gregor Jasny
 * `Helio Chissini de Castro <mailto:[email protected]>`_

Modules/CheckCSourceCompiles.cmake

@@ -77,7 +77,7 @@ and linked:
 
   include(CheckCSourceCompiles)
 
-  check_c_source_compiles("
+  check_c_source_compiles([[
     #include <emmintrin.h>
     int main(void)
     {
@@ -85,7 +85,7 @@ and linked:
       (void)a;
       return 0;
     }
-  " PROJECT_HAVE_SSE2_INTRINSICS)
+  ]] PROJECT_HAVE_SSE2_INTRINSICS)
 
 See Also
 ^^^^^^^^

Modules/CheckCSourceRuns.cmake

@@ -65,12 +65,12 @@ the check is stored in the internal cache variable ``HAVE_NORETURN``.
 
   include(CheckCSourceRuns)
 
-  check_c_source_runs("
+  check_c_source_runs([[
     #include <stdlib.h>
     #include <stdnoreturn.h>
     noreturn void f(){ exit(0); }
     int main(void) { f(); return 1; }
-  " HAVE_NORETURN)
+  ]] HAVE_NORETURN)
 
 See Also
 ^^^^^^^^

Modules/CheckCXXSourceCompiles.cmake

@@ -79,13 +79,13 @@ in the internal cache variable ``HAVE_CXX11_LAMBDAS``:
 
   include(CheckCXXSourceCompiles)
 
-  check_cxx_source_compiles("
+  check_cxx_source_compiles([[
     int main()
     {
       auto lambda = []() { return 42; };
       return lambda();
     }
-  " HAVE_CXX11_LAMBDAS)
+  ]] HAVE_CXX11_LAMBDAS)
 
 See Also
 ^^^^^^^^

Modules/CheckSourceCompiles.cmake

@@ -111,13 +111,13 @@ result is stored in the internal cache variable ``HAVE_CXX11_LAMBDAS``:
 
   include(CheckSourceCompiles)
 
-  check_source_compiles(CXX "
+  check_source_compiles(CXX [[
     int main()
     {
       auto lambda = []() { return 42; };
       return lambda();
     }
-  " HAVE_CXX11_LAMBDAS)
+  ]] HAVE_CXX11_LAMBDAS)
 
 Example: Checking Code With Bracket Argument
 """"""""""""""""""""""""""""""""""""""""""""
@@ -179,7 +179,7 @@ checking whether the PostgreSQL ``PGVerbosity`` enum contains
     cmake_push_check_state(RESET)
       set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL)
 
-      check_source_compiles(C "
+      check_source_compiles(C [[
         #include <libpq-fe.h>
         int main(void)
         {
@@ -187,7 +187,7 @@ checking whether the PostgreSQL ``PGVerbosity`` enum contains
           (void)e;
           return 0;
         }
-      " HAVE_PQERRORS_SQLSTATE)
+      ]] HAVE_PQERRORS_SQLSTATE)
     cmake_pop_check_state()
   endif()
 

Modules/CheckSourceRuns.cmake

@@ -96,12 +96,12 @@ the check is stored in the internal cache variable ``HAVE_NORETURN``.
 
   include(CheckSourceRuns)
 
-  check_source_runs(C "
+  check_source_runs(C [[
     #include <stdlib.h>
     #include <stdnoreturn.h>
     noreturn void f(){ exit(0); }
     int main(void) { f(); return 1; }
-  " HAVE_NORETURN)
+  ]] HAVE_NORETURN)
 
 Example: Checking Fortran Code
 """"""""""""""""""""""""""""""
@@ -112,12 +112,12 @@ Checking if Fortran source code runs successfully:
 
   include(CheckSourceRuns)
 
-  check_source_runs(Fortran "
+  check_source_runs(Fortran [[
     program test
     real :: x[*]
     call co_sum(x)
     end program
-  " HAVE_COARRAY)
+  ]] HAVE_COARRAY)
 
 Example: Checking C++ Code With Bracket Argument
 """"""""""""""""""""""""""""""""""""""""""""""""
@@ -171,7 +171,7 @@ successfully and stores a boolean result in the internal cache variable
       set(CMAKE_REQUIRED_LIBRARIES gnu)
     endif()
 
-    check_source_runs(C "
+    check_source_runs(C [[
       #include <sched.h>
       int main(void)
       {
@@ -180,7 +180,7 @@ successfully and stores a boolean result in the internal cache variable
         }
         return 0;
       }
-    " HAVE_SCHED_GETCPU)
+    ]] HAVE_SCHED_GETCPU)
   cmake_pop_check_state()
 
 See Also

Utilities/Sphinx/cmake.py

@@ -62,6 +62,9 @@ from pygments.token import (Comment, Name, Number, Operator, Punctuation,
 #   be present.
 
 CMakeLexer.tokens["root"] = [
+  # [[string]]
+  (r'\[\[(?:\W[\w\W]*?)?\]\]', String.Multiline),
+  (r'\[(?P<level>=+)\[[\w\W]*?\](?P=level)\]', String.Multiline),
   # fctn(
   (r'\b(\w+)([ \t]*)(\()',
    bygroups(Name.Function, Text, Name.Function), '#push'),