[FileCheck] Implement --ignore-case option.

The FileCheck utility is enhanced to support a `--ignore-case`
option. This is useful in cases where the output of Unix tools
differs in case (e.g. case not specified by Posix).

Reviewers: Bigcheese, jakehehrlich, rupprecht, espindola, alexshap, jhenderson, MaskRay

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

llvm-svn: 374339

1 files changed, 706 insertions, 701 deletions

diff --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst
index e8b324d..7d8ecaa 100644
--- a/llvm/docs/CommandGuide/FileCheck.rst
+++ b/llvm/docs/CommandGuide/FileCheck.rst
@@ -1,701 +1,706 @@
-FileCheck - Flexible pattern matching file verifier
-===================================================
-
-.. program:: FileCheck
-
-SYNOPSIS
---------
-
-:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
-
-DESCRIPTION
------------
-
-:program:`FileCheck` reads two files (one from standard input, and one
-specified on the command line) and uses one to verify the other.  This
-behavior is particularly useful for the testsuite, which wants to verify that
-the output of some tool (e.g. :program:`llc`) contains the expected information
-(for example, a movsd from esp or whatever is interesting).  This is similar to
-using :program:`grep`, but it is optimized for matching multiple different
-inputs in one file in a specific order.
-
-The ``match-filename`` file specifies the file that contains the patterns to
-match.  The file to verify is read from standard input unless the
-:option:`--input-file` option is used.
-
-OPTIONS
--------
-
-Options are parsed from the environment variable ``FILECHECK_OPTS``
-and from the command line.
-
-.. option:: -help
-
- Print a summary of command line options.
-
-.. option:: --check-prefix prefix
-
- FileCheck searches the contents of ``match-filename`` for patterns to
- match.  By default, these patterns are prefixed with "``CHECK:``".
- If you'd like to use a different prefix (e.g. because the same input
- file is checking multiple different tool or options), the
- :option:`--check-prefix` argument allows you to specify one or more
- prefixes to match. Multiple prefixes are useful for tests which might
- change for different run options, but most lines remain the same.
-
-.. option:: --check-prefixes prefix1,prefix2,...
-
- An alias of :option:`--check-prefix` that allows multiple prefixes to be
- specified as a comma separated list.
-
-.. option:: --input-file filename
-
-  File to check (defaults to stdin).
-
-.. option:: --match-full-lines
-
- By default, FileCheck allows matches of anywhere on a line. This
- option will require all positive matches to cover an entire
- line. Leading and trailing whitespace is ignored, unless
- :option:`--strict-whitespace` is also specified. (Note: negative
- matches from ``CHECK-NOT`` are not affected by this option!)
-
- Passing this option is equivalent to inserting ``{{^ *}}`` or
- ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive
- check pattern.
-
-.. option:: --strict-whitespace
-
- By default, FileCheck canonicalizes input horizontal whitespace (spaces and
- tabs) which causes it to ignore these differences (a space will match a tab).
- The :option:`--strict-whitespace` argument disables this behavior. End-of-line
- sequences are canonicalized to UNIX-style ``\n`` in all modes.
-
-.. option:: --implicit-check-not check-pattern
-
-  Adds implicit negative checks for the specified patterns between positive
-  checks. The option allows writing stricter tests without stuffing them with
-  ``CHECK-NOT``\ s.
-
-  For example, "``--implicit-check-not warning:``" can be useful when testing
-  diagnostic messages from tools that don't have an option similar to ``clang
-  -verify``. With this option FileCheck will verify that input does not contain
-  warnings not covered by any ``CHECK:`` patterns.
-
-.. option:: --dump-input <mode>
-
-  Dump input to stderr, adding annotations representing currently enabled
-  diagnostics.  Do this either 'always', on 'fail', or 'never'.  Specify 'help'
-  to explain the dump format and quit.
-
-.. option:: --dump-input-on-failure
-
-  When the check fails, dump all of the original input.  This option is
-  deprecated in favor of `--dump-input=fail`.
-
-.. option:: --enable-var-scope
-
-  Enables scope for regex variables.
-
-  Variables with names that start with ``$`` are considered global and
-  remain set throughout the file.
-
-  All other variables get undefined after each encountered ``CHECK-LABEL``.
-
-.. option:: -D<VAR=VALUE>
-
-  Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be
-  used in ``CHECK:`` lines.
-
-.. option:: -D#<NUMVAR>=<NUMERIC EXPRESSION>
-
-  Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating
-  ``<NUMERIC EXPRESSION>`` that can be used in ``CHECK:`` lines. See section
-  ``FileCheck Numeric Variables and Expressions`` for details on supported
-  numeric expressions.
-
-.. option:: -version
-
- Show the version number of this program.
-
-.. option:: -v
-
-  Print good directive pattern matches.  However, if ``-input-dump=fail`` or
-  ``-input-dump=always``, add those matches as input annotations instead.
-
-.. option:: -vv
-
-  Print information helpful in diagnosing internal FileCheck issues, such as
-  discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
-  and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.
-  However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
-  information as input annotations instead.
-
-.. option:: --allow-deprecated-dag-overlap
-
-  Enable overlapping among matches in a group of consecutive ``CHECK-DAG:``
-  directives.  This option is deprecated and is only provided for convenience
-  as old tests are migrated to the new non-overlapping ``CHECK-DAG:``
-  implementation.
-
-.. option:: --color
-
-  Use colors in output (autodetected by default).
-
-EXIT STATUS
------------
-
-If :program:`FileCheck` verifies that the file matches the expected contents,
-it exits with 0.  Otherwise, if not, or if an error occurs, it will exit with a
-non-zero value.
-
-TUTORIAL
---------
-
-FileCheck is typically used from LLVM regression tests, being invoked on the RUN
-line of the test.  A simple example of using FileCheck from a RUN line looks
-like this:
-
-.. code-block:: llvm
-
-   ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
-
-This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe
-that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``.  This
-means that FileCheck will be verifying its standard input (the llc output)
-against the filename argument specified (the original ``.ll`` file specified by
-"``%s``").  To see how this works, let's look at the rest of the ``.ll`` file
-(after the RUN line):
-
-.. code-block:: llvm
-
-   define void @sub1(i32* %p, i32 %v) {
-   entry:
-   ; CHECK: sub1:
-   ; CHECK: subl
-           %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
-           ret void
-   }
-
-   define void @inc4(i64* %p) {
-   entry:
-   ; CHECK: inc4:
-   ; CHECK: incq
-           %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
-           ret void
-   }
-
-Here you can see some "``CHECK:``" lines specified in comments.  Now you can
-see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
-output is what we are verifying.  FileCheck checks the machine code output to
-verify that it matches what the "``CHECK:``" lines specify.
-
-The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that
-must occur in order.  FileCheck defaults to ignoring horizontal whitespace
-differences (e.g. a space is allowed to match a tab) but otherwise, the contents
-of the "``CHECK:``" line is required to match some thing in the test file exactly.
-
-One nice thing about FileCheck (compared to grep) is that it allows merging
-test cases together into logical groups.  For example, because the test above
-is checking for the "``sub1:``" and "``inc4:``" labels, it will not match
-unless there is a "``subl``" in between those labels.  If it existed somewhere
-else in the file, that would not count: "``grep subl``" matches if "``subl``"
-exists anywhere in the file.
-
-The FileCheck -check-prefix option
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The FileCheck `-check-prefix` option allows multiple test
-configurations to be driven from one `.ll` file.  This is useful in many
-circumstances, for example, testing different architectural variants with
-:program:`llc`.  Here's a simple example:
-
-.. code-block:: llvm
-
-   ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
-   ; RUN:              | FileCheck %s -check-prefix=X32
-   ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
-   ; RUN:              | FileCheck %s -check-prefix=X64
-
-   define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
-           %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
-           ret <4 x i32> %tmp1
-   ; X32: pinsrd_1:
-   ; X32:    pinsrd $1, 4(%esp), %xmm0
-
-   ; X64: pinsrd_1:
-   ; X64:    pinsrd $1, %edi, %xmm0
-   }
-
-In this case, we're testing that we get the expected code generation with
-both 32-bit and 64-bit code generation.
-
-The "CHECK-NEXT:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes you want to match lines and would like to verify that matches
-happen on exactly consecutive lines with no other lines in between them.  In
-this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify
-this.  If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``".
-For example, something like this works as you'd expect:
-
-.. code-block:: llvm
-
-   define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
- 	%tmp3 = load <2 x double>* %A, align 16
- 	%tmp7 = insertelement <2 x double> undef, double %B, i32 0
- 	%tmp9 = shufflevector <2 x double> %tmp3,
-                               <2 x double> %tmp7,
-                               <2 x i32> < i32 0, i32 2 >
- 	store <2 x double> %tmp9, <2 x double>* %r, align 16
- 	ret void
-
-   ; CHECK:          t2:
-   ; CHECK: 	        movl	8(%esp), %eax
-   ; CHECK-NEXT: 	movapd	(%eax), %xmm0
-   ; CHECK-NEXT: 	movhpd	12(%esp), %xmm0
-   ; CHECK-NEXT: 	movl	4(%esp), %eax
-   ; CHECK-NEXT: 	movapd	%xmm0, (%eax)
-   ; CHECK-NEXT: 	ret
-   }
-
-"``CHECK-NEXT:``" directives reject the input unless there is exactly one
-newline between it and the previous directive.  A "``CHECK-NEXT:``" cannot be
-the first directive in a file.
-
-The "CHECK-SAME:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes you want to match lines and would like to verify that matches happen
-on the same line as the previous match.  In this case, you can use "``CHECK:``"
-and "``CHECK-SAME:``" directives to specify this.  If you specified a custom
-check prefix, just use "``<PREFIX>-SAME:``".
-
-"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
-(described below).
-
-For example, the following works like you'd expect:
-
-.. code-block:: llvm
-
-   !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
-
-   ; CHECK:       !DILocation(line: 5,
-   ; CHECK-NOT:               column:
-   ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]
-
-"``CHECK-SAME:``" directives reject the input if there are any newlines between
-it and the previous directive.  A "``CHECK-SAME:``" cannot be the first
-directive in a file.
-
-The "CHECK-EMPTY:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to check that the next line has nothing on it, not even whitespace,
-you can use the "``CHECK-EMPTY:``" directive.
-
-.. code-block:: llvm
-
-   declare void @foo()
-
-   declare void @bar()
-   ; CHECK: foo
-   ; CHECK-EMPTY:
-   ; CHECK-NEXT: bar
-
-Just like "``CHECK-NEXT:``" the directive will fail if there is more than one
-newline before it finds the next blank line, and it cannot be the first
-directive in a file.
-
-The "CHECK-NOT:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur
-between two matches (or before the first match, or after the last match).  For
-example, to verify that a load is removed by a transformation, a test like this
-can be used:
-
-.. code-block:: llvm
-
-   define i8 @coerce_offset0(i32 %V, i32* %P) {
-     store i32 %V, i32* %P
-
-     %P2 = bitcast i32* %P to i8*
-     %P3 = getelementptr i8* %P2, i32 2
-
-     %A = load i8* %P3
-     ret i8 %A
-   ; CHECK: @coerce_offset0
-   ; CHECK-NOT: load
-   ; CHECK: ret i8
-   }
-
-The "CHECK-COUNT:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to match multiple lines with the same pattern over and over again
-you can repeat a plain ``CHECK:`` as many times as needed. If that looks too
-boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where
-``<num>`` is a positive decimal number. It will match the pattern exactly
-``<num>`` times, no more and no less. If you specified a custom check prefix,
-just use "``<PREFIX>-COUNT-<num>:``" for the same effect.
-Here is a simple example:
-
-.. code-block:: text
-
-   Loop at depth 1
-   Loop at depth 1
-   Loop at depth 1
-   Loop at depth 1
-     Loop at depth 2
-       Loop at depth 3
-
-   ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
-   ; CHECK-NOT:     Loop at depth {{[0-9]+}}
-
-The "CHECK-DAG:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If it's necessary to match strings that don't occur in a strictly sequential
-order, "``CHECK-DAG:``" could be used to verify them between two matches (or
-before the first match, or after the last match). For example, clang emits
-vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks
-in the natural order:
-
-.. code-block:: c++
-
-    // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
-
-    struct Foo { virtual void method(); };
-    Foo f;  // emit vtable
-    // CHECK-DAG: @_ZTV3Foo =
-
-    struct Bar { virtual void method(); };
-    Bar b;
-    // CHECK-DAG: @_ZTV3Bar =
-
-``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to
-exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,
-the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all
-occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind
-occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,
-
-.. code-block:: llvm
-
-   ; CHECK-DAG: BEFORE
-   ; CHECK-NOT: NOT
-   ; CHECK-DAG: AFTER
-
-This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.
-
-With captured variables, ``CHECK-DAG:`` is able to match valid topological
-orderings of a DAG with edges from the definition of a variable to its use.
-It's useful, e.g., when your test cases need to match different output
-sequences from the instruction scheduler. For example,
-
-.. code-block:: llvm
-
-   ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
-   ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
-   ; CHECK:     mul r5, [[REG1]], [[REG2]]
-
-In this case, any order of that two ``add`` instructions will be allowed.
-
-If you are defining `and` using variables in the same ``CHECK-DAG:`` block,
-be aware that the definition rule can match `after` its use.
-
-So, for instance, the code below will pass:
-
-.. code-block:: text
-
-  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
-  ; CHECK-DAG: vmov.32 [[REG2]][1]
-  vmov.32 d0[1]
-  vmov.32 d0[0]
-
-While this other code, will not:
-
-.. code-block:: text
-
-  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
-  ; CHECK-DAG: vmov.32 [[REG2]][1]
-  vmov.32 d1[1]
-  vmov.32 d0[0]
-
-While this can be very useful, it's also dangerous, because in the case of
-register sequence, you must have a strong order (read before write, copy before
-use, etc). If the definition your test is looking for doesn't match (because
-of a bug in the compiler), it may match further away from the use, and mask
-real bugs away.
-
-In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.
-
-A ``CHECK-DAG:`` directive skips matches that overlap the matches of any
-preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block.  Not only
-is this non-overlapping behavior consistent with other directives, but it's
-also necessary to handle sets of non-unique strings or patterns.  For example,
-the following directives look for unordered log entries for two tasks in a
-parallel program, such as the OpenMP runtime:
-
-.. code-block:: text
-
-    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
-    // CHECK-DAG: [[THREAD_ID]]: task_end
-    //
-    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
-    // CHECK-DAG: [[THREAD_ID]]: task_end
-
-The second pair of directives is guaranteed not to match the same log entries
-as the first pair even though the patterns are identical and even if the text
-of the log entries is identical because the thread ID manages to be reused.
-
-The "CHECK-LABEL:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes in a file containing multiple tests divided into logical blocks, one
-or more ``CHECK:`` directives may inadvertently succeed by matching lines in a
-later block. While an error will usually eventually be generated, the check
-flagged as causing the error may not actually bear any relationship to the
-actual source of the problem.
-
-In order to produce better error messages in these cases, the "``CHECK-LABEL:``"
-directive can be used. It is treated identically to a normal ``CHECK``
-directive except that FileCheck makes an additional assumption that a line
-matched by the directive cannot also be matched by any other check present in
-``match-filename``; this is intended to be used for lines containing labels or
-other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides
-the input stream into separate blocks, each of which is processed independently,
-preventing a ``CHECK:`` directive in one block matching a line in another block.
-If ``--enable-var-scope`` is in effect, all local variables are cleared at the
-beginning of the block.
-
-For example,
-
-.. code-block:: llvm
-
-  define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
-  entry:
-  ; CHECK-LABEL: C_ctor_base:
-  ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0
-  ; CHECK: bl A_ctor_base
-  ; CHECK: mov r0, [[SAVETHIS]]
-    %0 = bitcast %struct.C* %this to %struct.A*
-    %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
-    %1 = bitcast %struct.C* %this to %struct.B*
-    %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
-    ret %struct.C* %this
-  }
-
-  define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
-  entry:
-  ; CHECK-LABEL: D_ctor_base:
-
-The use of ``CHECK-LABEL:`` directives in this case ensures that the three
-``CHECK:`` directives only accept lines corresponding to the body of the
-``@C_ctor_base`` function, even if the patterns match lines found later in
-the file. Furthermore, if one of these three ``CHECK:`` directives fail,
-FileCheck will recover by continuing to the next block, allowing multiple test
-failures to be detected in a single invocation.
-
-There is no requirement that ``CHECK-LABEL:`` directives contain strings that
-correspond to actual syntactic labels in a source or output language: they must
-simply uniquely match a single line in the file being verified.
-
-``CHECK-LABEL:`` directives cannot contain variable definitions or uses.
-
-FileCheck Regex Matching Syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All FileCheck directives take a pattern to match.
-For most uses of FileCheck, fixed string matching is perfectly sufficient.  For
-some things, a more flexible form of matching is desired.  To support this,
-FileCheck allows you to specify regular expressions in matching strings,
-surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX
-regular expression matcher; it supports Extended POSIX regular expressions
-(ERE). Because we want to use fixed string matching for a majority of what we
-do, FileCheck has been designed to support mixing and matching fixed string
-matching with regular expressions.  This allows you to write things like this:
-
-.. code-block:: llvm
-
-   ; CHECK: movhpd	{{[0-9]+}}(%esp), {{%xmm[0-7]}}
-
-In this case, any offset from the ESP register will be allowed, and any xmm
-register will be allowed.
-
-Because regular expressions are enclosed with double braces, they are
-visually distinct, and you don't need to use escape characters within the double
-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.  Or if you are using the repetition count
-syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you
-would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid
-confusion with FileCheck's closing double-brace.
-
-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 string substitution blocks that allow
-string variables to be defined and substituted into patterns.  Here is a simple
-example:
-
-.. code-block:: llvm
-
-   ; CHECK: test5:
-   ; CHECK:    notw	[[REGISTER:%[a-z]+]]
-   ; CHECK:    andw	{{.*}}[[REGISTER]]
-
-The first check line matches a regex ``%[a-z]+`` and captures it into the
-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 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
-
-    ; CHECK: op [[REG:r[0-9]+]], [[REG]]
-
-Can be useful if you want the operands of ``op`` to be the same register,
-and don't care exactly which register it is.
-
-If ``--enable-var-scope`` is in effect, variables with names that
-start with ``$`` are considered to be global. All others variables are
-local.  All local variables get undefined at the beginning of each
-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 Substitution Blocks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:program:`FileCheck` also supports numeric substitution blocks that allow
-defining numeric variables and checking for numeric values that satisfy a
-numeric expression constraint based on those variables via a numeric
-substitution. 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 define a numeric variable is ``[[#<NUMVAR>:]]`` where
-``<NUMVAR>`` is the name of the numeric variable to define to the matching
-value.
-
-For example:
-
-.. code-block:: llvm
-
-    ; CHECK: mov r[[#REG:]], 42
-
-would match ``mov r5, 42`` and set ``REG`` to the value ``5``.
-
-The syntax of a numeric substitution is ``[[#<expr>]]`` where ``<expr>`` is an
-expression. An expression is recursively defined as:
-
-* a numeric operand, or
-* an expression followed by an operator and a numeric operand.
-
-A numeric operand is a previously defined numeric variable, or an integer
-literal. The supported operators are ``+`` and ``-``. Spaces are accepted
-before, after and between any of these elements.
-
-For example:
-
-.. code-block:: llvm
-
-    ; CHECK: load r[[#REG:]], [r0]
-    ; CHECK: load r[[#REG+1]], [r1]
-
-The above example would match the text:
-
-.. code-block:: gas
-
-    load r5, [r0]
-    load r6, [r1]
-
-but would not match the text:
-
-.. code-block:: gas
-
-    load r5, [r0]
-    load r7, [r1]
-
-due to ``7`` being unequal to ``5 + 1``.
-
-The syntax also supports an empty expression, equivalent to writing {{[0-9]+}},
-for cases where the input must contain a numeric value but the value itself
-does not matter:
-
-.. code-block:: gas
-
-    ; CHECK-NOT: mov r0, r[[#]]
-
-to check that a value is synthesized rather than moved around.
-
-A numeric variable can also be defined to the result of a numeric expression,
-in which case the numeric expression is checked and if verified the variable is
-assigned to the value. The unified syntax for both defining numeric variables
-and checking a numeric expression is thus ``[[#<NUMVAR>: <expr>]]`` with each
-element as described previously.
-
-The ``--enable-var-scope`` option has the same effect on numeric variables as
-on string variables.
-
-Important note: In its current implementation, an expression cannot use a
-numeric variable defined earlier in the same CHECK directive.
-
-FileCheck Pseudo Numeric Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes there's a need to verify output that contains line numbers of the
-match file, e.g. when testing compiler diagnostics.  This introduces a certain
-fragility of the match file structure, as "``CHECK:``" lines contain absolute
-line numbers in the same file, which have to be updated whenever line numbers
-change due to text addition or deletion.
-
-To support this case, FileCheck expressions understand the ``@LINE`` pseudo
-numeric variable which evaluates to the line number of the CHECK pattern where
-it is found.
-
-This way match patterns can be put near the relevant test lines and include
-relative line number references, for example:
-
-.. code-block:: c++
-
-   // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
-   // CHECK-NEXT: {{^int a}}
-   // CHECK-NEXT: {{^     \^}}
-   // CHECK-NEXT: {{^     ;}}
-   int a
-
-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.
-
-Matching Newline Characters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To match newline characters in regular expressions the character class
-``[[:space:]]`` can be used. For example, the following pattern:
-
-.. code-block:: c++
-
-   // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
-
-matches output of the form (from llvm-dwarfdump):
-
-.. code-block:: text
-
-       DW_AT_location [DW_FORM_sec_offset]   (0x00000233)
-       DW_AT_name [DW_FORM_strp]  ( .debug_str[0x000000c9] = "intd")
-
-letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 
-``0x00000233``, extracted from the line immediately preceding "``intd``".
+FileCheck - Flexible pattern matching file verifier

+===================================================

+

+.. program:: FileCheck

+

+SYNOPSIS

+--------

+

+:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]

+

+DESCRIPTION

+-----------

+

+:program:`FileCheck` reads two files (one from standard input, and one

+specified on the command line) and uses one to verify the other.  This

+behavior is particularly useful for the testsuite, which wants to verify that

+the output of some tool (e.g. :program:`llc`) contains the expected information

+(for example, a movsd from esp or whatever is interesting).  This is similar to

+using :program:`grep`, but it is optimized for matching multiple different

+inputs in one file in a specific order.

+

+The ``match-filename`` file specifies the file that contains the patterns to

+match.  The file to verify is read from standard input unless the

+:option:`--input-file` option is used.

+

+OPTIONS

+-------

+

+Options are parsed from the environment variable ``FILECHECK_OPTS``

+and from the command line.

+

+.. option:: -help

+

+ Print a summary of command line options.

+

+.. option:: --check-prefix prefix

+

+ FileCheck searches the contents of ``match-filename`` for patterns to

+ match.  By default, these patterns are prefixed with "``CHECK:``".

+ If you'd like to use a different prefix (e.g. because the same input

+ file is checking multiple different tool or options), the

+ :option:`--check-prefix` argument allows you to specify one or more

+ prefixes to match. Multiple prefixes are useful for tests which might

+ change for different run options, but most lines remain the same.

+

+.. option:: --check-prefixes prefix1,prefix2,...

+

+ An alias of :option:`--check-prefix` that allows multiple prefixes to be

+ specified as a comma separated list.

+

+.. option:: --input-file filename

+

+  File to check (defaults to stdin).

+

+.. option:: --match-full-lines

+

+ By default, FileCheck allows matches of anywhere on a line. This

+ option will require all positive matches to cover an entire

+ line. Leading and trailing whitespace is ignored, unless

+ :option:`--strict-whitespace` is also specified. (Note: negative

+ matches from ``CHECK-NOT`` are not affected by this option!)

+

+ Passing this option is equivalent to inserting ``{{^ *}}`` or

+ ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive

+ check pattern.

+

+.. option:: --strict-whitespace

+

+ By default, FileCheck canonicalizes input horizontal whitespace (spaces and

+ tabs) which causes it to ignore these differences (a space will match a tab).

+ The :option:`--strict-whitespace` argument disables this behavior. End-of-line

+ sequences are canonicalized to UNIX-style ``\n`` in all modes.

+

+.. option:: --ignore-case

+

+  By default, FileCheck uses case-sensitive matching. This option causes

+  FileCheck to use case-insensitive matching.

+

+.. option:: --implicit-check-not check-pattern

+

+  Adds implicit negative checks for the specified patterns between positive

+  checks. The option allows writing stricter tests without stuffing them with

+  ``CHECK-NOT``\ s.

+

+  For example, "``--implicit-check-not warning:``" can be useful when testing

+  diagnostic messages from tools that don't have an option similar to ``clang

+  -verify``. With this option FileCheck will verify that input does not contain

+  warnings not covered by any ``CHECK:`` patterns.

+

+.. option:: --dump-input <mode>

+

+  Dump input to stderr, adding annotations representing currently enabled

+  diagnostics.  Do this either 'always', on 'fail', or 'never'.  Specify 'help'

+  to explain the dump format and quit.

+

+.. option:: --dump-input-on-failure

+

+  When the check fails, dump all of the original input.  This option is

+  deprecated in favor of `--dump-input=fail`.

+

+.. option:: --enable-var-scope

+

+  Enables scope for regex variables.

+

+  Variables with names that start with ``$`` are considered global and

+  remain set throughout the file.

+

+  All other variables get undefined after each encountered ``CHECK-LABEL``.

+

+.. option:: -D<VAR=VALUE>

+

+  Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be

+  used in ``CHECK:`` lines.

+

+.. option:: -D#<NUMVAR>=<NUMERIC EXPRESSION>

+

+  Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating

+  ``<NUMERIC EXPRESSION>`` that can be used in ``CHECK:`` lines. See section

+  ``FileCheck Numeric Variables and Expressions`` for details on supported

+  numeric expressions.

+

+.. option:: -version

+

+ Show the version number of this program.

+

+.. option:: -v

+

+  Print good directive pattern matches.  However, if ``-input-dump=fail`` or

+  ``-input-dump=always``, add those matches as input annotations instead.

+

+.. option:: -vv

+

+  Print information helpful in diagnosing internal FileCheck issues, such as

+  discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,

+  and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.

+  However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that

+  information as input annotations instead.

+

+.. option:: --allow-deprecated-dag-overlap

+

+  Enable overlapping among matches in a group of consecutive ``CHECK-DAG:``

+  directives.  This option is deprecated and is only provided for convenience

+  as old tests are migrated to the new non-overlapping ``CHECK-DAG:``

+  implementation.

+

+.. option:: --color

+

+  Use colors in output (autodetected by default).

+

+EXIT STATUS

+-----------

+

+If :program:`FileCheck` verifies that the file matches the expected contents,

+it exits with 0.  Otherwise, if not, or if an error occurs, it will exit with a

+non-zero value.

+

+TUTORIAL

+--------

+

+FileCheck is typically used from LLVM regression tests, being invoked on the RUN

+line of the test.  A simple example of using FileCheck from a RUN line looks

+like this:

+

+.. code-block:: llvm

+

+   ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s

+

+This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe

+that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``.  This

+means that FileCheck will be verifying its standard input (the llc output)

+against the filename argument specified (the original ``.ll`` file specified by

+"``%s``").  To see how this works, let's look at the rest of the ``.ll`` file

+(after the RUN line):

+

+.. code-block:: llvm

+

+   define void @sub1(i32* %p, i32 %v) {

+   entry:

+   ; CHECK: sub1:

+   ; CHECK: subl

+           %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)

+           ret void

+   }

+

+   define void @inc4(i64* %p) {

+   entry:

+   ; CHECK: inc4:

+   ; CHECK: incq

+           %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)

+           ret void

+   }

+

+Here you can see some "``CHECK:``" lines specified in comments.  Now you can

+see how the file is piped into ``llvm-as``, then ``llc``, and the machine code

+output is what we are verifying.  FileCheck checks the machine code output to

+verify that it matches what the "``CHECK:``" lines specify.

+

+The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that

+must occur in order.  FileCheck defaults to ignoring horizontal whitespace

+differences (e.g. a space is allowed to match a tab) but otherwise, the contents

+of the "``CHECK:``" line is required to match some thing in the test file exactly.

+

+One nice thing about FileCheck (compared to grep) is that it allows merging

+test cases together into logical groups.  For example, because the test above

+is checking for the "``sub1:``" and "``inc4:``" labels, it will not match

+unless there is a "``subl``" in between those labels.  If it existed somewhere

+else in the file, that would not count: "``grep subl``" matches if "``subl``"

+exists anywhere in the file.

+

+The FileCheck -check-prefix option

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+The FileCheck `-check-prefix` option allows multiple test

+configurations to be driven from one `.ll` file.  This is useful in many

+circumstances, for example, testing different architectural variants with

+:program:`llc`.  Here's a simple example:

+

+.. code-block:: llvm

+

+   ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \

+   ; RUN:              | FileCheck %s -check-prefix=X32

+   ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \

+   ; RUN:              | FileCheck %s -check-prefix=X64

+

+   define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {

+           %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1

+           ret <4 x i32> %tmp1

+   ; X32: pinsrd_1:

+   ; X32:    pinsrd $1, 4(%esp), %xmm0

+

+   ; X64: pinsrd_1:

+   ; X64:    pinsrd $1, %edi, %xmm0

+   }

+

+In this case, we're testing that we get the expected code generation with

+both 32-bit and 64-bit code generation.

+

+The "CHECK-NEXT:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Sometimes you want to match lines and would like to verify that matches

+happen on exactly consecutive lines with no other lines in between them.  In

+this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify

+this.  If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``".

+For example, something like this works as you'd expect:

+

+.. code-block:: llvm

+

+   define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {

+ 	%tmp3 = load <2 x double>* %A, align 16

+ 	%tmp7 = insertelement <2 x double> undef, double %B, i32 0

+ 	%tmp9 = shufflevector <2 x double> %tmp3,

+                               <2 x double> %tmp7,

+                               <2 x i32> < i32 0, i32 2 >

+ 	store <2 x double> %tmp9, <2 x double>* %r, align 16

+ 	ret void

+

+   ; CHECK:          t2:

+   ; CHECK: 	        movl	8(%esp), %eax

+   ; CHECK-NEXT: 	movapd	(%eax), %xmm0

+   ; CHECK-NEXT: 	movhpd	12(%esp), %xmm0

+   ; CHECK-NEXT: 	movl	4(%esp), %eax

+   ; CHECK-NEXT: 	movapd	%xmm0, (%eax)

+   ; CHECK-NEXT: 	ret

+   }

+

+"``CHECK-NEXT:``" directives reject the input unless there is exactly one

+newline between it and the previous directive.  A "``CHECK-NEXT:``" cannot be

+the first directive in a file.

+

+The "CHECK-SAME:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Sometimes you want to match lines and would like to verify that matches happen

+on the same line as the previous match.  In this case, you can use "``CHECK:``"

+and "``CHECK-SAME:``" directives to specify this.  If you specified a custom

+check prefix, just use "``<PREFIX>-SAME:``".

+

+"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"

+(described below).

+

+For example, the following works like you'd expect:

+

+.. code-block:: llvm

+

+   !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)

+

+   ; CHECK:       !DILocation(line: 5,

+   ; CHECK-NOT:               column:

+   ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]

+

+"``CHECK-SAME:``" directives reject the input if there are any newlines between

+it and the previous directive.  A "``CHECK-SAME:``" cannot be the first

+directive in a file.

+

+The "CHECK-EMPTY:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+If you need to check that the next line has nothing on it, not even whitespace,

+you can use the "``CHECK-EMPTY:``" directive.

+

+.. code-block:: llvm

+

+   declare void @foo()

+

+   declare void @bar()

+   ; CHECK: foo

+   ; CHECK-EMPTY:

+   ; CHECK-NEXT: bar

+

+Just like "``CHECK-NEXT:``" the directive will fail if there is more than one

+newline before it finds the next blank line, and it cannot be the first

+directive in a file.

+

+The "CHECK-NOT:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur

+between two matches (or before the first match, or after the last match).  For

+example, to verify that a load is removed by a transformation, a test like this

+can be used:

+

+.. code-block:: llvm

+

+   define i8 @coerce_offset0(i32 %V, i32* %P) {

+     store i32 %V, i32* %P

+

+     %P2 = bitcast i32* %P to i8*

+     %P3 = getelementptr i8* %P2, i32 2

+

+     %A = load i8* %P3

+     ret i8 %A

+   ; CHECK: @coerce_offset0

+   ; CHECK-NOT: load

+   ; CHECK: ret i8

+   }

+

+The "CHECK-COUNT:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+If you need to match multiple lines with the same pattern over and over again

+you can repeat a plain ``CHECK:`` as many times as needed. If that looks too

+boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where

+``<num>`` is a positive decimal number. It will match the pattern exactly

+``<num>`` times, no more and no less. If you specified a custom check prefix,

+just use "``<PREFIX>-COUNT-<num>:``" for the same effect.

+Here is a simple example:

+

+.. code-block:: text

+

+   Loop at depth 1

+   Loop at depth 1

+   Loop at depth 1

+   Loop at depth 1

+     Loop at depth 2

+       Loop at depth 3

+

+   ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}

+   ; CHECK-NOT:     Loop at depth {{[0-9]+}}

+

+The "CHECK-DAG:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+If it's necessary to match strings that don't occur in a strictly sequential

+order, "``CHECK-DAG:``" could be used to verify them between two matches (or

+before the first match, or after the last match). For example, clang emits

+vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks

+in the natural order:

+

+.. code-block:: c++

+

+    // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s

+

+    struct Foo { virtual void method(); };

+    Foo f;  // emit vtable

+    // CHECK-DAG: @_ZTV3Foo =

+

+    struct Bar { virtual void method(); };

+    Bar b;

+    // CHECK-DAG: @_ZTV3Bar =

+

+``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to

+exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,

+the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all

+occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind

+occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,

+

+.. code-block:: llvm

+

+   ; CHECK-DAG: BEFORE

+   ; CHECK-NOT: NOT

+   ; CHECK-DAG: AFTER

+

+This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.

+

+With captured variables, ``CHECK-DAG:`` is able to match valid topological

+orderings of a DAG with edges from the definition of a variable to its use.

+It's useful, e.g., when your test cases need to match different output

+sequences from the instruction scheduler. For example,

+

+.. code-block:: llvm

+

+   ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2

+   ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4

+   ; CHECK:     mul r5, [[REG1]], [[REG2]]

+

+In this case, any order of that two ``add`` instructions will be allowed.

+

+If you are defining `and` using variables in the same ``CHECK-DAG:`` block,

+be aware that the definition rule can match `after` its use.

+

+So, for instance, the code below will pass:

+

+.. code-block:: text

+

+  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]

+  ; CHECK-DAG: vmov.32 [[REG2]][1]

+  vmov.32 d0[1]

+  vmov.32 d0[0]

+

+While this other code, will not:

+

+.. code-block:: text

+

+  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]

+  ; CHECK-DAG: vmov.32 [[REG2]][1]

+  vmov.32 d1[1]

+  vmov.32 d0[0]

+

+While this can be very useful, it's also dangerous, because in the case of

+register sequence, you must have a strong order (read before write, copy before

+use, etc). If the definition your test is looking for doesn't match (because

+of a bug in the compiler), it may match further away from the use, and mask

+real bugs away.

+

+In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.

+

+A ``CHECK-DAG:`` directive skips matches that overlap the matches of any

+preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block.  Not only

+is this non-overlapping behavior consistent with other directives, but it's

+also necessary to handle sets of non-unique strings or patterns.  For example,

+the following directives look for unordered log entries for two tasks in a

+parallel program, such as the OpenMP runtime:

+

+.. code-block:: text

+

+    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin

+    // CHECK-DAG: [[THREAD_ID]]: task_end

+    //

+    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin

+    // CHECK-DAG: [[THREAD_ID]]: task_end

+

+The second pair of directives is guaranteed not to match the same log entries

+as the first pair even though the patterns are identical and even if the text

+of the log entries is identical because the thread ID manages to be reused.

+

+The "CHECK-LABEL:" directive

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Sometimes in a file containing multiple tests divided into logical blocks, one

+or more ``CHECK:`` directives may inadvertently succeed by matching lines in a

+later block. While an error will usually eventually be generated, the check

+flagged as causing the error may not actually bear any relationship to the

+actual source of the problem.

+

+In order to produce better error messages in these cases, the "``CHECK-LABEL:``"

+directive can be used. It is treated identically to a normal ``CHECK``

+directive except that FileCheck makes an additional assumption that a line

+matched by the directive cannot also be matched by any other check present in

+``match-filename``; this is intended to be used for lines containing labels or

+other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides

+the input stream into separate blocks, each of which is processed independently,

+preventing a ``CHECK:`` directive in one block matching a line in another block.

+If ``--enable-var-scope`` is in effect, all local variables are cleared at the

+beginning of the block.

+

+For example,

+

+.. code-block:: llvm

+

+  define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {

+  entry:

+  ; CHECK-LABEL: C_ctor_base:

+  ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0

+  ; CHECK: bl A_ctor_base

+  ; CHECK: mov r0, [[SAVETHIS]]

+    %0 = bitcast %struct.C* %this to %struct.A*

+    %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)

+    %1 = bitcast %struct.C* %this to %struct.B*

+    %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)

+    ret %struct.C* %this

+  }

+

+  define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {

+  entry:

+  ; CHECK-LABEL: D_ctor_base:

+

+The use of ``CHECK-LABEL:`` directives in this case ensures that the three

+``CHECK:`` directives only accept lines corresponding to the body of the

+``@C_ctor_base`` function, even if the patterns match lines found later in

+the file. Furthermore, if one of these three ``CHECK:`` directives fail,

+FileCheck will recover by continuing to the next block, allowing multiple test

+failures to be detected in a single invocation.

+

+There is no requirement that ``CHECK-LABEL:`` directives contain strings that

+correspond to actual syntactic labels in a source or output language: they must

+simply uniquely match a single line in the file being verified.

+

+``CHECK-LABEL:`` directives cannot contain variable definitions or uses.

+

+FileCheck Regex Matching Syntax

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+All FileCheck directives take a pattern to match.

+For most uses of FileCheck, fixed string matching is perfectly sufficient.  For

+some things, a more flexible form of matching is desired.  To support this,

+FileCheck allows you to specify regular expressions in matching strings,

+surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX

+regular expression matcher; it supports Extended POSIX regular expressions

+(ERE). Because we want to use fixed string matching for a majority of what we

+do, FileCheck has been designed to support mixing and matching fixed string

+matching with regular expressions.  This allows you to write things like this:

+

+.. code-block:: llvm

+

+   ; CHECK: movhpd	{{[0-9]+}}(%esp), {{%xmm[0-7]}}

+

+In this case, any offset from the ESP register will be allowed, and any xmm

+register will be allowed.

+

+Because regular expressions are enclosed with double braces, they are

+visually distinct, and you don't need to use escape characters within the double

+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.  Or if you are using the repetition count

+syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you

+would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid

+confusion with FileCheck's closing double-brace.

+

+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 string substitution blocks that allow

+string variables to be defined and substituted into patterns.  Here is a simple

+example:

+

+.. code-block:: llvm

+

+   ; CHECK: test5:

+   ; CHECK:    notw	[[REGISTER:%[a-z]+]]

+   ; CHECK:    andw	{{.*}}[[REGISTER]]

+

+The first check line matches a regex ``%[a-z]+`` and captures it into the

+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 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

+

+    ; CHECK: op [[REG:r[0-9]+]], [[REG]]

+

+Can be useful if you want the operands of ``op`` to be the same register,

+and don't care exactly which register it is.

+

+If ``--enable-var-scope`` is in effect, variables with names that

+start with ``$`` are considered to be global. All others variables are

+local.  All local variables get undefined at the beginning of each

+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 Substitution Blocks

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+:program:`FileCheck` also supports numeric substitution blocks that allow

+defining numeric variables and checking for numeric values that satisfy a

+numeric expression constraint based on those variables via a numeric

+substitution. 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 define a numeric variable is ``[[#<NUMVAR>:]]`` where

+``<NUMVAR>`` is the name of the numeric variable to define to the matching

+value.

+

+For example:

+

+.. code-block:: llvm

+

+    ; CHECK: mov r[[#REG:]], 42

+

+would match ``mov r5, 42`` and set ``REG`` to the value ``5``.

+

+The syntax of a numeric substitution is ``[[#<expr>]]`` where ``<expr>`` is an

+expression. An expression is recursively defined as:

+

+* a numeric operand, or

+* an expression followed by an operator and a numeric operand.

+

+A numeric operand is a previously defined numeric variable, or an integer

+literal. The supported operators are ``+`` and ``-``. Spaces are accepted

+before, after and between any of these elements.

+

+For example:

+

+.. code-block:: llvm

+

+    ; CHECK: load r[[#REG:]], [r0]

+    ; CHECK: load r[[#REG+1]], [r1]

+

+The above example would match the text:

+

+.. code-block:: gas

+

+    load r5, [r0]

+    load r6, [r1]

+

+but would not match the text:

+

+.. code-block:: gas

+

+    load r5, [r0]

+    load r7, [r1]

+

+due to ``7`` being unequal to ``5 + 1``.

+

+The syntax also supports an empty expression, equivalent to writing {{[0-9]+}},

+for cases where the input must contain a numeric value but the value itself

+does not matter:

+

+.. code-block:: gas

+

+    ; CHECK-NOT: mov r0, r[[#]]

+

+to check that a value is synthesized rather than moved around.

+

+A numeric variable can also be defined to the result of a numeric expression,

+in which case the numeric expression is checked and if verified the variable is

+assigned to the value. The unified syntax for both defining numeric variables

+and checking a numeric expression is thus ``[[#<NUMVAR>: <expr>]]`` with each

+element as described previously.

+

+The ``--enable-var-scope`` option has the same effect on numeric variables as

+on string variables.

+

+Important note: In its current implementation, an expression cannot use a

+numeric variable defined earlier in the same CHECK directive.

+

+FileCheck Pseudo Numeric Variables

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Sometimes there's a need to verify output that contains line numbers of the

+match file, e.g. when testing compiler diagnostics.  This introduces a certain

+fragility of the match file structure, as "``CHECK:``" lines contain absolute

+line numbers in the same file, which have to be updated whenever line numbers

+change due to text addition or deletion.

+

+To support this case, FileCheck expressions understand the ``@LINE`` pseudo

+numeric variable which evaluates to the line number of the CHECK pattern where

+it is found.

+

+This way match patterns can be put near the relevant test lines and include

+relative line number references, for example:

+

+.. code-block:: c++

+

+   // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator

+   // CHECK-NEXT: {{^int a}}

+   // CHECK-NEXT: {{^     \^}}

+   // CHECK-NEXT: {{^     ;}}

+   int a

+

+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.

+

+Matching Newline Characters

+~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+To match newline characters in regular expressions the character class

+``[[:space:]]`` can be used. For example, the following pattern:

+

+.. code-block:: c++

+

+   // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"

+

+matches output of the form (from llvm-dwarfdump):

+

+.. code-block:: text

+

+       DW_AT_location [DW_FORM_sec_offset]   (0x00000233)

+       DW_AT_name [DW_FORM_strp]  ( .debug_str[0x000000c9] = "intd")

+

+letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 

+``0x00000233``, extracted from the line immediately preceding "``intd``".