[dexter] Add keyword argument 'on_line' to DexLabel

[Orlando]

Summary

Add optional keyword argument 'on_line' to DexLabel to label the specifed line
instead of the line the command is found on.

This will be helpful when used alongside DexDeclareFile (D99651).

[Orlando]

+ Update Commands.md

[TWeaver]

Nice! LGTM

debuginfo-tests/dexter/Commands.md

 The condition is only evaluated on the line 'from_line' or 'on_line'. If the
 condition is not true at the start of the range, the whole range is ignored.
 
 DexLimitSteps commands are useful for reducing the amount of steps gathered in
 large test cases that would normally take much longer to complete.
 
 ----
 ## DexLabel
-    DexLabel(name)
+    DexLabel(name [, **on_line])
 
     Args:
         name (str): A unique name for this line.
 
+    Keyword args:
+        on_line (int): Specify a line number to label.
+
 ### Description
-Name the line this command is found on. Line names can be referenced by other
-commands expecting line number arguments.
+Name the line this command is found on or 'on_line' if it is provided. Line
+names can be referenced by other commands expecting line number arguments.
 For example, `DexExpectWatchValues(..., on_line='my_line_name')`.
 
 ### Heuristic
 This command does not contribute to the heuristic score.
 
 
 ---
 ## DexWatch

debuginfo-tests/dexter/dex/command/commands/DexLabel.py

 # DExTer : Debugging Experience Tester
 # ~~~~~~   ~         ~~         ~   ~~
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 """Command used to give a line in a test a named psuedonym. Every DexLabel has
    a line number and Label string component.
 """
 
 from dex.command.CommandBase import CommandBase
 
 
 class DexLabel(CommandBase):
-    def __init__(self, label):
+    def __init__(self, label, **kwargs):
 
         if not isinstance(label, str):
             raise TypeError('invalid argument type')
 
+        try:
+            self.on_line = kwargs.pop('on_line')
+        except KeyError:
+            # We cannot use self.lineno because it hasn't been set yet.
+            pass
+        if kwargs:
+            raise TypeError(f'unexpected named args: {", ".join(kwargs)}')
+
         self._label = label
         super(DexLabel, self).__init__()
 
+    def get_line(self):
+        return getattr(self, 'on_line', self.lineno)
+
     def get_as_pair(self):
-        return (self._label, self.lineno)
+        return (self._label, self.get_line())
 
     @staticmethod
     def get_name():
         return __class__.__name__
 
     def eval(self):
         return self._label

debuginfo-tests/dexter/feature_tests/subtools/test/err_label_kwarg.cpp

+// Purpose:
+//    Check that bad keyword args in \DexLabel are reported.
+//    Use --binary switch to trick dexter into skipping the build step.
+//
+// RUN: not %dexter_base test --binary %s --debugger 'lldb' -- %s | FileCheck %s
+// CHECK: parser error:{{.*}}err_label_kwarg.cpp(8): unexpected named args: bad_arg
+
+// DexLabel('test', bad_arg=0)

debuginfo-tests/dexter/feature_tests/subtools/test/label_another_line.cpp

+// Purpose:
+//    Check that the optional keyword argument 'on_line' makes a \DexLabel label
+//    that line instead of the line the command is found on.
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: label_another_line.cpp: (1.0000)
+
+int main() {
+  int result = 0;
+  return result;
+}
+
+// DexLabel('test', on_line=10)
+// DexExpectWatchValue('result', '0', on_line='test')