mirror of
https://github.com/Kitware/CMake.git
synced 2026-06-24 08:47:59 +00:00
7fdf315ba3
When a built-in cache variable is set via `-D <var>=<value>` with no help text supplied, populate `HELPSTRING` from the built-in documentation table (sourced from `Help/variable/*.rst` and the per-language pattern manuals). Project-defined and unknown variables continue to receive the legacy "No help, variable specified on the command line." sentinel. The cache entry's type and value are left untouched: type stays `UNINITIALIZED` for bare `-D` and an explicit `-D <var>:TYPE=<value>` is honored as before. The `cmCacheManager::LoadCache` path is not modified, so reload of existing caches is a fixed point. Fixes: #27830
85 lines
3.3 KiB
C++
85 lines
3.3 KiB
C++
/* Distributed under the OSI-approved BSD 3-Clause License. See accompanying
|
|
file LICENSE.rst or https://cmake.org/licensing for details. */
|
|
#pragma once
|
|
|
|
#include "cmConfigure.h" // IWYU pragma: keep
|
|
|
|
#include <cstddef>
|
|
|
|
#include <cm/string_view>
|
|
|
|
#include "cmCacheDocumentationTable.h"
|
|
|
|
/** \namespace cmCachePatternTable
|
|
* \brief Compile-time pattern-matching fallback for built-in CMake cache
|
|
* variable documentation.
|
|
*
|
|
* The pattern table is a hand-maintained list of placeholder-shaped
|
|
* tooltips, e.g. ``CMAKE_<LANG>_FLAGS`` or
|
|
* ``CMAKE_POLICY_DEFAULT_CMP<NNNN>``, that complement the exact-match
|
|
* entries in ``cmCacheDocumentationTable``. It is consulted only on
|
|
* the miss path: ``cmCacheDocumentationTable::Get`` first attempts an
|
|
* exact-match lookup, then falls back to ``cmCachePatternTable::Match``
|
|
* for names that follow a known template shape.
|
|
*
|
|
* Placeholder lexical classes recognized by the matcher (see
|
|
* ``cmCachePatternTable.cxx`` for details):
|
|
*
|
|
* * ``<LANG>``, ``<CONFIG>``, ``<PackageName>``: identifier
|
|
* (``[A-Za-z][A-Za-z0-9_]*``).
|
|
* * ``<PROJECT-NAME>``, ``<an-attribute>``: identifier with
|
|
* hyphens (``[A-Za-z][A-Za-z0-9_-]*``).
|
|
* * ``<NNNN>``: exactly 4 ASCII digits (``[0-9]{4}``).
|
|
* * ``<n>``: exactly 1 ASCII digit (``[0-9]``).
|
|
*
|
|
* Matching is leftmost-anchor, lazy on each placeholder, with full
|
|
* input consumption required at the end. The matcher is intentionally
|
|
* permissive: per-language or per-configuration restrictions documented
|
|
* in the corresponding ``Help/variable/<NAME>.rst`` file are reproduced
|
|
* in the entry's Summary prose, not enforced by the matcher. First
|
|
* fully-matching entry in ``kPatterns[]`` wins; entries are kept in
|
|
* ``(numPlaceholders ASC, totalLiteralLen DESC, Pattern ASC)`` order so
|
|
* that more-specific patterns are tried before less specific ones.
|
|
*/
|
|
namespace cmCachePatternTable {
|
|
|
|
/** \brief A single row in the pattern documentation table.
|
|
*
|
|
* The ``Pattern`` and ``Summary`` views reference storage with static
|
|
* lifetime. ``Pattern`` is a literal template string containing one or
|
|
* more angle-bracketed placeholders such as ``<LANG>`` or ``<NNNN>``.
|
|
*/
|
|
struct Entry
|
|
{
|
|
cm::string_view Pattern;
|
|
cm::string_view Summary;
|
|
};
|
|
|
|
/** \brief Look up the built-in documentation for \a varName by pattern.
|
|
*
|
|
* Walks ``kPatterns[]`` in declaration order and returns the first
|
|
* entry whose ``Pattern`` template fully matches \a varName under the
|
|
* lexical classes above. On miss returns an empty ``Summary``.
|
|
* Performs no allocation; runs in ``O(N * |varName|)`` for the small
|
|
* (~30) table.
|
|
*
|
|
* The result type is reused from ``cmCacheDocumentationTable`` so that
|
|
* the single call site in ``cmCacheDocumentationTable::Get`` can return
|
|
* either an exact-match or a pattern-match result without translation.
|
|
*/
|
|
cmCacheDocumentationTable::LookupResult Match(cm::string_view varName);
|
|
|
|
/** \brief Iterate the underlying pattern table.
|
|
*
|
|
* Exposed for the ``testCacheDocumentationTable`` unit test in
|
|
* ``Tests/CMakeLib``, which verifies that the entries are well-formed
|
|
* and obey the canonical ordering rule. Callers should not rely on a
|
|
* particular entry count or ordering beyond what the unit test
|
|
* asserts.
|
|
*/
|
|
Entry const* EntriesBegin();
|
|
Entry const* EntriesEnd();
|
|
std::size_t EntriesSize();
|
|
|
|
}
|