From efcf318f8d56a8bc405fa4af3d4c4b7e8227da3c Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 22 Oct 2013 18:11:22 -0400 Subject: Add \-continuation to CMake language quoted arguments Teach the CMake language lexer to treat the \-LF pair terminating a line ending in an odd number of backslashes inside a quoted argument as a continuation. Drop the pair from the returned quoted argument token text. This will allow long lines inside quoted argument strings to be divided across multiple lines in the source file. It will also allow quoted argument text to start on the line after the opening quote. For example, the code: set(x "\ ...") sets variable "x" to the value "..." with no opening newline. Previously an odd number of backslashes at the end of a line inside a quoted argument would put a \-LF pair (or a \-CR pair) literally in the argument. Then the command-argument evaluator would complain that the \-escape sequence is invalid. Therefore this syntax is available to use without changing behavior of valid existing code. Teach the RunCMake.Syntax test to cover cases of quoted arguments with lines ending in \, \\, and \\\. Odd counts are continuations. --- Source/cmListFileLexer.c | 2 +- Source/cmListFileLexer.in.l | 2 +- Tests/RunCMake/Syntax/RunCMakeTest.cmake | 3 +++ Tests/RunCMake/Syntax/StringBackslash-result.txt | 1 + Tests/RunCMake/Syntax/StringBackslash-stderr.txt | 6 ++++++ Tests/RunCMake/Syntax/StringBackslash.cmake | 2 ++ Tests/RunCMake/Syntax/StringContinuation1-result.txt | 1 + Tests/RunCMake/Syntax/StringContinuation1-stderr.txt | 4 ++++ Tests/RunCMake/Syntax/StringContinuation1.cmake | 2 ++ Tests/RunCMake/Syntax/StringContinuation2-result.txt | 1 + Tests/RunCMake/Syntax/StringContinuation2-stderr.txt | 4 ++++ Tests/RunCMake/Syntax/StringContinuation2.cmake | 2 ++ 12 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 Tests/RunCMake/Syntax/StringBackslash-result.txt create mode 100644 Tests/RunCMake/Syntax/StringBackslash-stderr.txt create mode 100644 Tests/RunCMake/Syntax/StringBackslash.cmake create mode 100644 Tests/RunCMake/Syntax/StringContinuation1-result.txt create mode 100644 Tests/RunCMake/Syntax/StringContinuation1-stderr.txt create mode 100644 Tests/RunCMake/Syntax/StringContinuation1.cmake create mode 100644 Tests/RunCMake/Syntax/StringContinuation2-result.txt create mode 100644 Tests/RunCMake/Syntax/StringContinuation2-stderr.txt create mode 100644 Tests/RunCMake/Syntax/StringContinuation2.cmake diff --git a/Source/cmListFileLexer.c b/Source/cmListFileLexer.c index 3b08b03..be27884 100644 --- a/Source/cmListFileLexer.c +++ b/Source/cmListFileLexer.c @@ -1127,7 +1127,7 @@ case 17: YY_RULE_SETUP #line 224 "cmListFileLexer.in.l" { - cmListFileLexerAppend(lexer, yytext, yyleng); + /* Continuation: text is not part of string */ ++lexer->line; lexer->column = 1; } diff --git a/Source/cmListFileLexer.in.l b/Source/cmListFileLexer.in.l index ecaf156..d45a8ea 100644 --- a/Source/cmListFileLexer.in.l +++ b/Source/cmListFileLexer.in.l @@ -222,7 +222,7 @@ LEGACY {MAKEVAR}|{UNQUOTED}|\"({MAKEVAR}|{UNQUOTED}|[ \t[=])*\" } \\\n { - cmListFileLexerAppend(lexer, yytext, yyleng); + /* Continuation: text is not part of string */ ++lexer->line; lexer->column = 1; } diff --git a/Tests/RunCMake/Syntax/RunCMakeTest.cmake b/Tests/RunCMake/Syntax/RunCMakeTest.cmake index f5e0d11..2d49f76 100644 --- a/Tests/RunCMake/Syntax/RunCMakeTest.cmake +++ b/Tests/RunCMake/Syntax/RunCMakeTest.cmake @@ -14,7 +14,10 @@ run_cmake(CommandError1) run_cmake(CommandError2) run_cmake(String0) run_cmake(String1) +run_cmake(StringBackslash) run_cmake(StringCRLF) +run_cmake(StringContinuation1) +run_cmake(StringContinuation2) run_cmake(StringNoSpace) run_cmake(OneLetter) run_cmake(Unquoted0) diff --git a/Tests/RunCMake/Syntax/StringBackslash-result.txt b/Tests/RunCMake/Syntax/StringBackslash-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/Syntax/StringBackslash-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/Syntax/StringBackslash-stderr.txt b/Tests/RunCMake/Syntax/StringBackslash-stderr.txt new file mode 100644 index 0000000..214f914 --- /dev/null +++ b/Tests/RunCMake/Syntax/StringBackslash-stderr.txt @@ -0,0 +1,6 @@ +CMake Error at StringBackslash.cmake:1 \(message\): + a\\ + + b +Call Stack \(most recent call first\): + CMakeLists.txt:3 \(include\) diff --git a/Tests/RunCMake/Syntax/StringBackslash.cmake b/Tests/RunCMake/Syntax/StringBackslash.cmake new file mode 100644 index 0000000..066be96 --- /dev/null +++ b/Tests/RunCMake/Syntax/StringBackslash.cmake @@ -0,0 +1,2 @@ +message(FATAL_ERROR "a\\ +b") diff --git a/Tests/RunCMake/Syntax/StringContinuation1-result.txt b/Tests/RunCMake/Syntax/StringContinuation1-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation1-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/Syntax/StringContinuation1-stderr.txt b/Tests/RunCMake/Syntax/StringContinuation1-stderr.txt new file mode 100644 index 0000000..05771da --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation1-stderr.txt @@ -0,0 +1,4 @@ +CMake Error at StringContinuation1.cmake:1 \(message\): + ab +Call Stack \(most recent call first\): + CMakeLists.txt:3 \(include\) diff --git a/Tests/RunCMake/Syntax/StringContinuation1.cmake b/Tests/RunCMake/Syntax/StringContinuation1.cmake new file mode 100644 index 0000000..ae86bb2 --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation1.cmake @@ -0,0 +1,2 @@ +message(FATAL_ERROR "a\ +b") diff --git a/Tests/RunCMake/Syntax/StringContinuation2-result.txt b/Tests/RunCMake/Syntax/StringContinuation2-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation2-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/Syntax/StringContinuation2-stderr.txt b/Tests/RunCMake/Syntax/StringContinuation2-stderr.txt new file mode 100644 index 0000000..2f4964c --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation2-stderr.txt @@ -0,0 +1,4 @@ +CMake Error at StringContinuation2.cmake:1 \(message\): + a\\b +Call Stack \(most recent call first\): + CMakeLists.txt:3 \(include\) diff --git a/Tests/RunCMake/Syntax/StringContinuation2.cmake b/Tests/RunCMake/Syntax/StringContinuation2.cmake new file mode 100644 index 0000000..490a408 --- /dev/null +++ b/Tests/RunCMake/Syntax/StringContinuation2.cmake @@ -0,0 +1,2 @@ +message(FATAL_ERROR "a\\\ +b") -- cgit v0.12 From 8bb2ee96cc8ae16d039a648c87004e828e9cba16 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 23 Oct 2013 09:14:30 -0400 Subject: cmake-developer.7: Improve flow of module documentation instructions Use prose instead of enumerated steps and re-order the steps so that the cmake-module directive is covered contiguously. --- Help/manual/cmake-developer.7.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index eace3a4..f6b8150 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -230,30 +230,31 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files. Module Documentation -------------------- -To add a module to the CMake documentation, follow these steps: +To document CMake module ``Modules/.cmake``, modify +``Help/manual/cmake-modules.7.rst`` to reference the module in the +``toctree`` directive, in sorted order, as:: -1. Add file ``Help/module/.rst`` containing just the line:: + /module/ - .. cmake-module:: ../../Modules/.cmake +Then add the module document file ``Help/module/.rst`` +containing just the line:: -2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the - toctree directive as:: + .. cmake-module:: ../../Modules/.cmake - /module/ +The ``cmake-module`` directive will scan the module file to extract +reStructuredText markup from comment blocks that start in ``.rst:``. +Add to the top of ``Modules/.cmake`` a #-comment of the form: - Keep the toctree in sorted order! - -3. Add to the top of ``Modules/.cmake`` a #-comment of the form:: +.. code-block:: cmake - #.rst: - # - # ------------- - # - # ...reStructuredText documentation of module... + #.rst: + # + # ------------- + # + # - Comment blocks starting with the line ``#.rst:`` may appear anywhere - in the file. The ``cmake-module`` directive used above will scan the - file to extract reStructuredText markup from such comments. +Additional such ``.rst:`` comments may appear anywhere in the module file. +All such comments must start with ``#`` in the first column. For example, a ``Modules/Findxxx.cmake`` module may contain: -- cgit v0.12 From 2945814de29923b8f063fa179f282fbbae630a36 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 22 Oct 2013 19:49:45 -0400 Subject: cmRST: Teach cmake-module directive to scan bracket comments When scanning CMake module files for .rst comments, recognize bracket comments starting in ".rst:" too. For example: #[[.rst: Include the bracket comment content terminated by the closing bracket. Exclude the line containing the bracket if it starts in "#". Teach the CMakeLib.testRST test to cover multiple bracket lengths and ending brackets on lines with and without "#". Update the cmake-developer.7 manual to document the bracket-comment syntax for .rst documentation. --- Help/manual/cmake-developer.7.rst | 28 +++++++++++++++++----- Source/cmRST.cxx | 50 ++++++++++++++++++++++++++++++--------- Source/cmRST.h | 1 + Tests/CMakeLib/testRST.expect | 6 +++++ Tests/CMakeLib/testRSTmod.cmake | 7 ++++++ Utilities/Sphinx/cmake.py | 37 +++++++++++++++++++++-------- 6 files changed, 102 insertions(+), 27 deletions(-) diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index f6b8150..198a240 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -253,6 +253,21 @@ Add to the top of ``Modules/.cmake`` a #-comment of the form: # # +or a bracket-comment of the form: + +.. code-block:: cmake + + #[[.rst: + + ------------- + + + #]] + +Any number of ``=`` may be used in the opening and closing brackets +as long as they match. Content on the line containing the closing +bracket is excluded if and only if the line starts in ``#``. + Additional such ``.rst:`` comments may appear anywhere in the module file. All such comments must start with ``#`` in the first column. @@ -276,12 +291,13 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: - #.rst: - # .. command:: xxx_do_something - # - # This command does something for Xxx:: - # - # xxx_do_something(some arguments) + #[========================================[.rst: + .. command:: xxx_do_something + + This command does something for Xxx:: + + xxx_do_something(some arguments) + #]========================================] macro(xxx_do_something) endmacro() diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index d2eeb0c..6d4e281 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -34,6 +34,7 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot): ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"), IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"), TocTreeDirective("^.. toctree::[ \t]*(.*)$"), + ModuleRST("^#\\[(=*)\\[\\.rst:$"), CMakeRole("(:cmake)?:(" "command|generator|variable|module|policy|" "prop_cache|prop_dir|prop_gbl|prop_sf|prop_test|prop_tgt|" @@ -85,28 +86,55 @@ void cmRST::ProcessModule(std::istream& is) std::string rst; while(cmSystemTools::GetLineFromStream(is, line)) { - if(rst == "#") + if(!rst.empty() && rst != "#") { - if(line == "#") + // Bracket mode: check for end bracket + std::string::size_type pos = line.find(rst); + if(pos == line.npos) { - this->ProcessLine(""); - continue; - } - else if(line.substr(0, 2) == "# ") - { - this->ProcessLine(line.substr(2, line.npos)); - continue; + this->ProcessLine(line); } else { + if(line[0] != '#') + { + this->ProcessLine(line.substr(0, pos)); + } rst = ""; this->Reset(); this->OutputLinePending = true; } } - if(line == "#.rst:") + else { - rst = "#"; + // Line mode: check for .rst start (bracket or line) + if(rst == "#") + { + if(line == "#") + { + this->ProcessLine(""); + continue; + } + else if(line.substr(0, 2) == "# ") + { + this->ProcessLine(line.substr(2, line.npos)); + continue; + } + else + { + rst = ""; + this->Reset(); + this->OutputLinePending = true; + } + } + if(line == "#.rst:") + { + rst = "#"; + } + else if(this->ModuleRST.find(line)) + { + rst = "]" + this->ModuleRST.match(1) + "]"; + } } } if(rst == "#") diff --git a/Source/cmRST.h b/Source/cmRST.h index 1a3cd99..fa987cd 100644 --- a/Source/cmRST.h +++ b/Source/cmRST.h @@ -84,6 +84,7 @@ private: cmsys::RegularExpression ReplaceDirective; cmsys::RegularExpression IncludeDirective; cmsys::RegularExpression TocTreeDirective; + cmsys::RegularExpression ModuleRST; cmsys::RegularExpression CMakeRole; cmsys::RegularExpression Substitution; diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 9bd0ca4..744cb88 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -27,6 +27,12 @@ CMake Module Content More CMake Module Content +Bracket Comment Content + +[ +Bracket Comment Content +] + .. cmake:command:: some_cmd Command some_cmd description. diff --git a/Tests/CMakeLib/testRSTmod.cmake b/Tests/CMakeLib/testRSTmod.cmake index dfa793d..8b807a6 100644 --- a/Tests/CMakeLib/testRSTmod.cmake +++ b/Tests/CMakeLib/testRSTmod.cmake @@ -2,3 +2,10 @@ # CMake Module Content #.rst: # More CMake Module Content +#[[.rst: +Bracket Comment Content +# not part of content]] # not part of content +#[=[.rst: +[ +Bracket Comment Content +]]=] # not part of content diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index 75f62df..146e1f6 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -31,7 +31,6 @@ class CMakeModule(Directive): def __init__(self, *args, **keys): self.re_start = re.compile(r'^#\[(?P=*)\[\.rst:$') - self.re_end = re.compile(r'^#?\](?P=*)\]$') Directive.__init__(self, *args, **keys) def run(self): @@ -61,18 +60,36 @@ class CMakeModule(Directive): rst = None lines = [] for line in raw_lines: - if line == '#.rst:': - rst = '#' - line = '' - elif rst == '#': - if line == '#' or line[:2] == '# ': - line = line[2:] - else: + if rst is not None and rst != '#': + # Bracket mode: check for end bracket + pos = line.find(rst) + if pos >= 0: + if line[0] == '#': + line = '' + else: + line = line[0:pos] rst = None - line = '' else: - line = '' + # Line mode: check for .rst start (bracket or line) + m = self.re_start.match(line) + if m: + rst = ']%s]' % m.group('eq') + line = '' + elif line == '#.rst:': + rst = '#' + line = '' + elif rst == '#': + if line == '#' or line[:2] == '# ': + line = line[2:] + else: + rst = None + line = '' + elif rst is None: + line = '' lines.append(line) + if rst is not None and rst != '#': + raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' % + (self.name, rst[1:-1], path)) self.state_machine.insert_input(lines, path) return [] -- cgit v0.12