diff options
| -rw-r--r-- | Help/command/file.rst | 319 | ||||
| -rw-r--r-- | Help/command/install.rst | 42 | ||||
| -rw-r--r-- | Help/command/list.rst | 82 | ||||
| -rw-r--r-- | Help/command/string.rst | 111 | ||||
| -rw-r--r-- | Source/cmRST.cxx | 68 | ||||
| -rw-r--r-- | Source/cmRST.h | 2 | ||||
| -rw-r--r-- | Tests/CMakeLib/testRST.expect | 4 | ||||
| -rw-r--r-- | Tests/CMakeLib/testRST.rst | 4 | ||||
| -rw-r--r-- | Utilities/Sphinx/static/cmake.css | 10 |
9 files changed, 400 insertions, 242 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 43ce3d9..d4a6006 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,23 +3,44 @@ file File manipulation command. ------------------------------------------------------------------------------- +Synopsis +^^^^^^^^ -:: +.. parsed-literal:: - file(WRITE <filename> <content>...) - file(APPEND <filename> <content>...) + `Reading`_ + file(`READ`_ <filename> <out-var> [...]) + file(`STRINGS`_ <filename> <out-var> [...]) + file(`\<HASH\> <HASH_>`_ <filename> <out-var>) + file(`TIMESTAMP`_ <filename> <out-var> [...]) -Write ``<content>`` into a file called ``<filename>``. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ``<filename>`` that do not -exist will be created. + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname>) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ <out-var> <directory> <file>) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) + + `Transfer`_ + file(`DOWNLOAD`_ <url> <file> [...]) + file(`UPLOAD`_ <file> <url> [...]) ------------------------------------------------------------------------------- + `Locking`_ + file(`LOCK`_ <path> [...]) + +Reading +^^^^^^^ + +.. _READ: :: @@ -31,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a read at most ``<max-in>`` bytes. The ``HEX`` option causes data to be converted to a hexadecimal representation (useful for binary data). ------------------------------------------------------------------------------- +.. _STRINGS: :: @@ -82,7 +103,7 @@ For example, the code stores a list in the variable ``myfile`` in which each item is a line from the input file. ------------------------------------------------------------------------------- +.. _HASH: :: @@ -93,7 +114,108 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` command. ------------------------------------------------------------------------------- +.. _TIMESTAMP: + +:: + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +:: + + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) + +Write ``<content>`` into a file called ``<filename>``. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ``<filename>`` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +.. _TOUCH: +.. _TOUCH_NOCREATE: + +:: + + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +.. _GENERATE: + +:: + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ``<output-file>`` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: :: @@ -148,7 +270,7 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories ------------------------------------------------------------------------------- +.. _RENAME: :: @@ -157,7 +279,8 @@ Examples of recursive globbing include:: Move a file or directory within a filesystem from ``<oldname>`` to ``<newname>``, replacing the destination atomically. ------------------------------------------------------------------------------- +.. _REMOVE: +.. _REMOVE_RECURSE: :: @@ -168,7 +291,7 @@ Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a given file does not exist. ------------------------------------------------------------------------------- +.. _MAKE_DIRECTORY: :: @@ -176,7 +299,44 @@ given file does not exist. Create the given directories and their parents as needed. ------------------------------------------------------------------------------- +.. _COPY: +.. _INSTALL: + +:: + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: :: @@ -185,7 +345,8 @@ Create the given directories and their parents as needed. Compute the relative path from a ``<directory>`` to a ``<file>`` and store it in the ``<variable>``. ------------------------------------------------------------------------------- +.. _TO_CMAKE_PATH: +.. _TO_NATIVE_PATH: :: @@ -203,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). Always use double quotes around the ``<path>`` to be sure it is treated as a single argument to this command. ------------------------------------------------------------------------------- +Transfer +^^^^^^^^ + +.. _DOWNLOAD: +.. _UPLOAD: :: @@ -290,116 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. If neither ``TLS`` option is given CMake will check variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. ------------------------------------------------------------------------------- - -:: - - file(TOUCH [<files>...]) - file(TOUCH_NOCREATE [<files>...]) - -Create a file with no content if it does not yet exist. If the file already -exists, its access and/or modification will be updated to the time when the -function call is executed. - -Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file -does not exist it will be silently ignored. - -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. - ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP <filename> <variable> [<format>] [UTC]) - -Compute a string representation of the modification time of ``<filename>`` -and store it in ``<variable>``. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ``<format>`` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - <INPUT input-file|CONTENT content> - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator <cmake-generators(7)>`. Evaluate -:manual:`generator expressions <cmake-generator-expressions(7)>` -from the input content to produce the output content. The options are: - -``CONDITION <condition>`` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT <content>`` - Use the content given explicitly as input. - -``INPUT <input-file>`` - Use the content from a given file as input. - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - -``OUTPUT <output-file>`` - Specify the output file name to generate. Use generator expressions - such as ``$<CONFIG>`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ``<output-file>`` - must evaluate to an unique name for each configuration. - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. - -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- - -:: - - file(<COPY|INSTALL> <files>... DESTINATION <dir> - [FILE_PERMISSIONS <permissions>...] - [DIRECTORY_PERMISSIONS <permissions>...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN <pattern> | REGEX <regex>] - [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). +Locking +^^^^^^^ ------------------------------------------------------------------------------- +.. _LOCK: :: diff --git a/Help/command/install.rst b/Help/command/install.rst index a81714f..6cea996 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,19 +1,19 @@ install ------- -.. only:: html - - .. contents:: - Specify rules to run at install time. -This command accepts several signatures: +Synopsis +^^^^^^^^ -* :ref:`install(TARGETS) <install-targets>` -* :ref:`install(FILES|PROGRAMS) <install-files>` -* :ref:`install(DIRECTORY) <install-directory>` -* :ref:`install(SCRIPT|CODE) <install-script>` -* :ref:`install(EXPORT|EXPORT_ANDROID_MK) <install-export>` +.. parsed-literal:: + + install(`TARGETS`_ <target>... [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...]) + install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...]) + install(`SCRIPT`_ <file> [...]) + install(`CODE`_ <code> [...]) + install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) Introduction ^^^^^^^^^^^^ @@ -89,11 +89,11 @@ Command signatures that install files may print messages during installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable to control which messages are printed. -.. _install-targets: - Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _TARGETS: + :: install(TARGETS targets... [EXPORT <export-name>] @@ -284,11 +284,12 @@ The install destination given to the target install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-files: - Installing Files ^^^^^^^^^^^^^^^^ +.. _FILES: +.. _PROGRAMS: + :: install(<FILES|PROGRAMS> files... DESTINATION <dir> @@ -319,11 +320,11 @@ The install destination given to the files install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-directory: - Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _DIRECTORY: + :: install(DIRECTORY dirs... DESTINATION <dir> @@ -402,11 +403,12 @@ given to the directory install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-script: - Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _CODE: +.. _SCRIPT: + :: install([[SCRIPT <file>] [CODE <code>]] @@ -425,11 +427,11 @@ example, the code will print a message during installation. -.. _install-export: - Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _EXPORT: + :: install(EXPORT <export-name> DESTINATION <dir> diff --git a/Help/command/list.rst b/Help/command/list.rst index 67e9743..589e572 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -1,11 +1,37 @@ list ---- -.. only:: html +List operations. - .. contents:: +Synopsis +^^^^^^^^ -List operations. +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ <list> <out-var>) + list(`GET`_ <list> <element index> [<index> ...] <out-var>) + list(`JOIN`_ <list> <glue> <out-var>) + list(`SUBLIST`_ <list> <begin> <length> <out-var>) + + `Search`_ + list(`FIND`_ <list> <value> <out-var>) + + `Modification`_ + list(`APPEND`_ <list> [<element>...]) + list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) + list(`INSERT`_ <list> <index> [<element>...]) + list(`REMOVE_ITEM`_ <list> <value>...) + list(`REMOVE_AT`_ <list> <index>...) + list(`REMOVE_DUPLICATES`_ <list>) + list(`TRANSFORM`_ <list> <ACTION> [...]) + + `Ordering`_ + list(`REVERSE`_ <list>) + list(`SORT`_ <list>) + +Introduction +^^^^^^^^^^^^ The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create @@ -33,11 +59,10 @@ scope. To propagate the results of these operations upwards, use Be careful when counting with negative indices: they do not start from 0. -0 is equivalent to 0, the first list element. -Capacity and Element access -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Reading +^^^^^^^ -LENGTH -"""""" +.. _LENGTH: :: @@ -45,8 +70,7 @@ LENGTH Returns the list's length. -GET -""" +.. _GET: :: @@ -54,8 +78,7 @@ GET Returns the list of elements specified by indices from the list. -JOIN -"""" +.. _JOIN: :: @@ -65,8 +88,7 @@ Returns a string joining all list's elements using the glue string. To join multiple strings, which are not part of a list, use ``JOIN`` operator from :command:`string` command. -SUBLIST -""""""" +.. _SUBLIST: :: @@ -80,8 +102,7 @@ the remaining elements of the list starting at ``<begin>`` will be returned. Search ^^^^^^ -FIND -"""" +.. _FIND: :: @@ -93,8 +114,7 @@ if it wasn't found. Modification ^^^^^^^^^^^^ -APPEND -"""""" +.. _APPEND: :: @@ -102,8 +122,7 @@ APPEND Appends elements to the list. -FILTER -"""""" +.. _FILTER: :: @@ -115,8 +134,7 @@ In ``REGEX`` mode, items will be matched against the given regular expression. For more information on regular expressions see also the :command:`string` command. -INSERT -"""""" +.. _INSERT: :: @@ -124,8 +142,7 @@ INSERT Inserts elements to the list to the specified location. -REMOVE_ITEM -""""""""""" +.. _REMOVE_ITEM: :: @@ -133,8 +150,7 @@ REMOVE_ITEM Removes the given items from the list. -REMOVE_AT -""""""""" +.. _REMOVE_AT: :: @@ -142,8 +158,7 @@ REMOVE_AT Removes items at given indices from the list. -REMOVE_DUPLICATES -""""""""""""""""" +.. _REMOVE_DUPLICATES: :: @@ -151,8 +166,7 @@ REMOVE_DUPLICATES Removes duplicated items in the list. -TRANSFORM -""""""""" +.. _TRANSFORM: :: @@ -224,11 +238,10 @@ expression will be transformed. :: list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) -Sorting -^^^^^^^ +Ordering +^^^^^^^^ -REVERSE -""""""" +.. _REVERSE: :: @@ -236,8 +249,7 @@ REVERSE Reverses the contents of the list in-place. -SORT -"""" +.. _SORT: :: diff --git a/Help/command/string.rst b/Help/command/string.rst index e84f788..efa923b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,17 +1,52 @@ string ------ -.. only:: html - - .. contents:: - String operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) + string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) + string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) + + `Manipulation`_ + string(`APPEND`_ <string-var> [<input>...]) + string(`PREPEND`_ <string-var> [<input>...]) + string(`CONCAT`_ <out-var> [<input>...]) + string(`JOIN`_ <glue> <out-var> [<input>...]) + string(`TOLOWER`_ <string1> <out-var>) + string(`TOUPPER`_ <string1> <out-var>) + string(`LENGTH`_ <string> <out-var>) + string(`SUBSTRING`_ <string> <begin> <length> <out-var>) + string(`STRIP`_ <string> <out-var>) + string(`GENEX_STRIP`_ <string> <out-var>) + + `Comparison`_ + string(`COMPARE`_ <op> <string1> <string2> <out-var>) + + `Hashing`_ + string(`\<HASH\> <HASH_>`_ <out-var> <input>) + + `Generation`_ + string(`ASCII`_ <number>... <out-var>) + string(`CONFIGURE`_ <string1> <out-var> [...]) + string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) + string(`RANDOM`_ [<option>...] <out-var>) + string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) + string(`UUID`_ <out-var> ...) + Search and Replace ^^^^^^^^^^^^^^^^^^ -FIND -"""" +.. _FIND: :: @@ -22,8 +57,7 @@ the supplied string. If the ``REVERSE`` flag was used, the command will search for the position of the last occurrence of the specified substring. If the substring is not found, a position of -1 is returned. -REPLACE -""""""" +.. _REPLACE: :: @@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output. Regular Expressions ^^^^^^^^^^^^^^^^^^^ -REGEX MATCH -""""""""""" +.. _`REGEX MATCH`: :: @@ -48,8 +81,7 @@ REGEX MATCH Match the regular expression once and store the match in the output variable. All ``<input>`` arguments are concatenated before matching. -REGEX MATCHALL -"""""""""""""" +.. _`REGEX MATCHALL`: :: @@ -60,8 +92,7 @@ Match the regular expression as many times as possible and store the matches in the output variable as a list. All ``<input>`` arguments are concatenated before matching. -REGEX REPLACE -""""""""""""" +.. _`REGEX REPLACE`: :: @@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. Manipulation ^^^^^^^^^^^^ -APPEND -"""""" +.. _APPEND: :: @@ -132,8 +162,7 @@ APPEND Append all the input arguments to the string. -PREPEND -""""""" +.. _PREPEND: :: @@ -141,8 +170,7 @@ PREPEND Prepend all the input arguments to the string. -CONCAT -"""""" +.. _CONCAT: :: @@ -151,8 +179,7 @@ CONCAT Concatenate all the input arguments together and store the result in the named output variable. -JOIN -"""" +.. _JOIN: :: @@ -165,8 +192,7 @@ To join list's elements, use preferably the ``JOIN`` operator from :command:`list` command. This allows for the elements to have special characters like ``;`` in them. -TOLOWER -""""""" +.. _TOLOWER: :: @@ -174,8 +200,7 @@ TOLOWER Convert string to lower characters. -TOUPPER -""""""" +.. _TOUPPER: :: @@ -183,8 +208,7 @@ TOUPPER Convert string to upper characters. -LENGTH -"""""" +.. _LENGTH: :: @@ -192,8 +216,7 @@ LENGTH Store in an output variable a given string's length. -SUBSTRING -""""""""" +.. _SUBSTRING: :: @@ -207,8 +230,7 @@ If string is shorter than length then end of string is used instead. CMake 3.1 and below reported an error if length pointed past the end of string. -STRIP -""""" +.. _STRIP: :: @@ -217,8 +239,7 @@ STRIP Store in an output variable a substring of a given string with leading and trailing spaces removed. -GENEX_STRIP -""""""""""" +.. _GENEX_STRIP: :: @@ -230,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``. Comparison ^^^^^^^^^^ +.. _COMPARE: + :: string(COMPARE LESS <string1> <string2> <output variable>) @@ -246,6 +269,8 @@ Compare the strings and store true or false in the output variable. Hashing ^^^^^^^ +.. _`HASH`: + :: string(<HASH> <output variable> <input>) @@ -277,8 +302,7 @@ The supported ``<HASH>`` algorithm names are: Generation ^^^^^^^^^^ -ASCII -""""" +.. _ASCII: :: @@ -286,8 +310,7 @@ ASCII Convert all numbers into corresponding ASCII characters. -CONFIGURE -""""""""" +.. _CONFIGURE: :: @@ -296,8 +319,7 @@ CONFIGURE Transform a string like :command:`configure_file` transforms a file. -MAKE_C_IDENTIFIER -""""""""""""""""" +.. _MAKE_C_IDENTIFIER: :: @@ -308,8 +330,7 @@ underscore and store the result in the ``<output variable>``. If the first character of the string is a digit, an underscore will also be prepended to the result. -RANDOM -"""""" +.. _RANDOM: :: @@ -322,8 +343,7 @@ and default alphabet is all numbers and upper and lower case letters. If an integer ``RANDOM_SEED`` is given, its value will be used to seed the random number generator. -TIMESTAMP -""""""""" +.. _TIMESTAMP: :: @@ -378,8 +398,7 @@ If no explicit ``<format string>`` is given it will default to: its value will be used instead of the current time. See https://reproducible-builds.org/specs/source-date-epoch/ for details. -UUID -"""" +.. _UUID: :: diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index edcbc22..d9e5bcb 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -39,6 +39,8 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot) "prop_test|prop_tgt|" "manual" "):`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`") + , InlineLink("`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`_") + , InlineLiteral("``([^`]*)``") , Substitution("(^|[^A-Za-z0-9_])" "((\\|[^| \t\r\n]([^|\r\n]*[^| \t\r\n])?\\|)(__|_|))" "([^A-Za-z0-9_]|$)") @@ -245,18 +247,62 @@ void cmRST::OutputLine(std::string const& line_in, bool inlineMarkup) if (inlineMarkup) { std::string line = this->ReplaceSubstitutions(line_in); std::string::size_type pos = 0; - while (this->CMakeRole.find(line.c_str() + pos)) { - this->OS << line.substr(pos, this->CMakeRole.start()); - std::string text = this->CMakeRole.match(3); - // If a command reference has no explicit target and - // no explicit "(...)" then add "()" to the text. - if (this->CMakeRole.match(2) == "command" && - this->CMakeRole.match(5).empty() && - text.find_first_of("()") == std::string::npos) { - text += "()"; + for (;;) { + std::string::size_type* first = nullptr; + std::string::size_type role_start = std::string::npos; + std::string::size_type link_start = std::string::npos; + std::string::size_type lit_start = std::string::npos; + if (this->CMakeRole.find(line.c_str() + pos)) { + role_start = this->CMakeRole.start(); + first = &role_start; + } + if (this->InlineLiteral.find(line.c_str() + pos)) { + lit_start = this->InlineLiteral.start(); + if (!first || lit_start < *first) { + first = &lit_start; + } + } + if (this->InlineLink.find(line.c_str() + pos)) { + link_start = this->InlineLink.start(); + if (!first || link_start < *first) { + first = &link_start; + } + } + if (first == &role_start) { + this->OS << line.substr(pos, role_start); + std::string text = this->CMakeRole.match(3); + // If a command reference has no explicit target and + // no explicit "(...)" then add "()" to the text. + if (this->CMakeRole.match(2) == "command" && + this->CMakeRole.match(5).empty() && + text.find_first_of("()") == std::string::npos) { + text += "()"; + } + this->OS << "``" << text << "``"; + pos += this->CMakeRole.end(); + } else if (first == &lit_start) { + this->OS << line.substr(pos, lit_start); + std::string text = this->InlineLiteral.match(1); + pos += this->InlineLiteral.end(); + this->OS << "``" << text << "``"; + } else if (first == &link_start) { + this->OS << line.substr(pos, link_start); + std::string text = this->InlineLink.match(1); + bool escaped = false; + for (char c : text) { + if (escaped) { + escaped = false; + this->OS << c; + } else if (c == '\\') { + escaped = true; + } else { + this->OS << c; + } + } + pos += this->InlineLink.end(); + } else { + break; } - this->OS << "``" << text << "``"; - pos += this->CMakeRole.end(); } this->OS << line.substr(pos) << "\n"; } else { diff --git a/Source/cmRST.h b/Source/cmRST.h index d1a8e27..ee47867 100644 --- a/Source/cmRST.h +++ b/Source/cmRST.h @@ -85,6 +85,8 @@ private: cmsys::RegularExpression NoteDirective; cmsys::RegularExpression ModuleRST; cmsys::RegularExpression CMakeRole; + cmsys::RegularExpression InlineLink; + cmsys::RegularExpression InlineLiteral; cmsys::RegularExpression Substitution; cmsys::RegularExpression TocTreeLink; diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 4b29762..1ffd6b9 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -19,6 +19,10 @@ Variable ``VARIABLE_<PLACEHOLDER>`` with trailing placeholder and target. Environment variable ``SOME_ENV_VAR``. Environment variable ``some env var`` with space and target. Generator ``Some Generator`` with space. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline link Link Text. +Inline link Link Text <With \-escaped Brackets>. +Inline literal ``__`` followed by inline link Link Text. First TOC entry. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 9cd7257..c8587c0 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -26,6 +26,10 @@ Variable :variable:`VARIABLE_<PLACEHOLDER> <target>` with trailing placeholder a Environment variable :envvar:`SOME_ENV_VAR`. Environment variable :envvar:`some env var <SOME_ENV_VAR>` with space and target. Generator :generator:`Some Generator` with space. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline link `Link Text <ExternalDest>`_. +Inline link `Link Text \<With \\-escaped Brackets\> <ExternalDest>`_. +Inline literal ``__`` followed by inline link `Link Text <InternalDest_>`_. .. |not replaced| replace:: not replaced through toctree .. |not replaced in literal| replace:: replaced in parsed literal diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css index 2a326d4..b082ede 100644 --- a/Utilities/Sphinx/static/cmake.css +++ b/Utilities/Sphinx/static/cmake.css @@ -6,3 +6,13 @@ div.sphinxsidebarwrapper { word-wrap: break-word; } + +/* Make links inside parsed-literal blocks more obvious + by using a background color and increased line spacing + to make them look boxed. */ +.literal-block { + line-height: 1.4; +} +.literal-block a.reference.internal { + background-color: #dfdfdf; +} |