FileCheck: Improve FileCheck variable terminology

Summary:
Terminology introduced by [[#]] blocks is confusing and does not
integrate well with existing terminology.

First, variables referred by [[]] blocks are called "pattern variables"
while the text a CHECK directive needs to match is called a "CHECK
pattern". This is inconsistent with variables in [[#]] blocks since
[[#]] blocks are also found in CHECK pattern yet those variables are
called "numeric variable".

Second, the replacing of both [[]] and [[#]] blocks by the value of the
variable or expression they contain is represented by a
FileCheckPatternSubstitution class. The naming refers to being a
substitution in a CHECK pattern but could be wrongly understood as being
a substitution of a pattern variable.

Third and lastly, comments use "numeric expression" to refer both to the
[[#]] blocks as well as to the numeric expressions these blocks contain
which get evaluated at match time.

This patch solves these confusions by
- calling variables in [[]] and [[#]] blocks as string and numeric
  variables respectively;
- referring to [[]] and [[#]] as substitution *blocks*, with the former
  being a string substitution block and the latter a numeric
  substitution block;
- calling [[]] and [[#]] blocks to be replaced by the value of a
  variable or expression they contain a substitution (as opposed to
  definition when these blocks are used to defined a variable), with the
  former being a string substitution and the latter a numeric
  substitution;
- renaming the FileCheckPatternSubstitution as a FileCheckSubstitution
  class with FileCheckStringSubstitution and
  FileCheckNumericSubstitution subclasses;
- restricting the use of "numeric expression" to refer to the expression
  that is evaluated in a numeric substitution.

While numeric substitution blocks only support numeric substitutions of
numeric expressions at the moment there are plans to augment numeric
substitution blocks to support numeric definitions as well as both a
numeric definition and numeric substitution in the same numeric
substitution block.

Reviewers: jhenderson, jdenny, probinson, arichardson

Subscribers: hiraditya, arichardson, probinson, llvm-commits

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D62146

llvm-svn: 361445

1 files changed, 35 insertions, 28 deletions

diff --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst
index bc216be35df..e54ab762cd2 100644
--- a/llvm/docs/CommandGuide/FileCheck.rst
+++ b/llvm/docs/CommandGuide/FileCheck.rst
@@ -499,8 +499,8 @@ simply uniquely match a single line in the file being verified.
 
 ``CHECK-LABEL:`` directives cannot contain variable definitions or uses.
 
-FileCheck Pattern Matching Syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+FileCheck Regex Matching Syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All FileCheck directives take a pattern to match.
 For most uses of FileCheck, fixed string matching is perfectly sufficient.  For
@@ -525,14 +525,15 @@ braces like you would in C.  In the rare case that you want to match double
 braces explicitly from the input, you can use something ugly like
 ``{{[{][{]}}`` as your pattern.
 
-FileCheck Pattern Expressions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+FileCheck String Substitution Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is often useful to match a pattern and then verify that it occurs again
-later in the file.  For codegen tests, this can be useful to allow any register,
-but verify that that register is used consistently later.  To do this,
-:program:`FileCheck` supports pattern expressions that allow pattern variables
-to be defined and substituted into patterns.  Here is a simple example:
+later in the file.  For codegen tests, this can be useful to allow any
+register, but verify that that register is used consistently later.  To do
+this, :program:`FileCheck` supports string substitution blocks that allow
+string variables to be defined and substituted into patterns.  Here is a simple
+example:
 
 .. code-block:: llvm
 
@@ -541,15 +542,16 @@ to be defined and substituted into patterns.  Here is a simple example:
    ; CHECK:    andw	{{.*}}[[REGISTER]]
 
 The first check line matches a regex ``%[a-z]+`` and captures it into the
-variable ``REGISTER``.  The second line verifies that whatever is in
-``REGISTER`` occurs later in the file after an "``andw``".  :program:`FileCheck`
-variable references are always contained in ``[[ ]]`` pairs, and their names can
-be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``.  If a colon follows the name,
-then it is a definition of the variable; otherwise, it is a use.
+string variable ``REGISTER``.  The second line verifies that whatever is in
+``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`
+string substitution blocks are always contained in ``[[ ]]`` pairs, and string
+variable names can be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``.  If a
+colon follows the name, then it is a definition of the variable; otherwise, it
+is a substitution.
 
-:program:`FileCheck` variables can be defined multiple times, and uses always
-get the latest value.  Variables can also be used later on the same line they
-were defined on. For example:
+:program:`FileCheck` variables can be defined multiple times, and substitutions
+always get the latest value.  Variables can also be substituted later on the
+same line they were defined on. For example:
 
 .. code-block:: llvm
 
@@ -565,16 +567,17 @@ CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.
 This makes it easier to ensure that individual tests are not affected
 by variables set in preceding tests.
 
-FileCheck Numeric Variables and Expressions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+FileCheck Numeric Substitution Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:program:`FileCheck` also allows checking for numeric values that satisfy a
-numeric expression constraint based on numeric variables. This allows
-``CHECK:`` directives to verify a numeric relation between two numbers, such as
-the need for consecutive registers to be used.
+:program:`FileCheck` also supports numeric substitution blocks that allow
+checking for numeric values that satisfy a numeric expression constraint based
+on numeric variables. This allows ``CHECK:`` directives to verify a numeric
+relation between two numbers, such as the need for consecutive registers to be
+used.
 
-The syntax to check a numeric expression constraint is
-``[[#<NUMVAR><op><offset>]]`` where:
+The syntax of a numeric substitution block is ``[[#<NUMVAR><op><offset>]]``
+where:
 
 * ``<NUMVAR>`` is the name of a numeric variable defined on the command line.
 
@@ -585,6 +588,10 @@ The syntax to check a numeric expression constraint is
   the numeric operation <op>. It must be present if ``<op>`` is present,
   absent otherwise.
 
+Spaces are accepted before, after and between any of these elements.
+
+Unlike string substitution blocks, numeric substitution blocks only introduce
+numeric substitutions which substitute a numeric expression for its value.
 For example:
 
 .. code-block:: llvm
@@ -606,7 +613,7 @@ but would not match the line:
 due to ``7`` being unequal to ``5 + 1``.
 
 The ``--enable-var-scope`` option has the same effect on numeric variables as
-on pattern variables.
+on string variables.
 
 FileCheck Pseudo Numeric Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -632,9 +639,9 @@ relative line number references, for example:
    // CHECK-NEXT: {{^     ;}}
    int a
 
-To support legacy uses of ``@LINE`` as a special pattern variable,
-:program:`FileCheck` also accepts the following uses of ``@LINE`` with pattern
-variable syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
+To support legacy uses of ``@LINE`` as a special string variable,
+:program:`FileCheck` also accepts the following uses of ``@LINE`` with string
+substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
 ``[[@LINE-<offset>]]`` without any spaces inside the brackets and where
 ``offset`` is an integer.