[lldb/DataFormatters] Fix the `$$deference$$` synthetic child

[friss]

Summary

The ValueObject code checks for a special $$dereference$$ synthetic
child to allow formatter providers to implement a natural
dereferencing behavior in frame variable for objects like smart
pointers.

This support was broken when used directly throught the Python API and
not trhough frame variable. The reason is that
SBFrame.FindVariable() will return by default the synthetic variable
if it exists, while frame variable will not do this eagerly. The
code in ValueObject::Dereference() accounted for the latter but not
for the former. The fix is trivial. The test change includes
additional covergage for the already-working bahevior as it wasn't
covered by the testsuite before.

This commit also adds a short piece of documentatione explaining that
it is possible (even advisable) to provide this synthetic child
outstide of the range of the normal children.

[JDevlieghere]

lldb/docs/use/variable.rst

895

You can enable syntax highlighting for this snippet by using .. code-block:: python instead.

[friss]

use python formatting in docs

[jingham]

Except for one typo in the comment (thanks for adding that BTW) looks good.

lldb/docs/use/variable.rst

907

of -> from

lldb/docs/use/variable.rst

 information. In the example, we can use synthetic children to provide the
 vector items as children for the std::vector object.
 
 In order to create synthetic children, you need to provide a Python class that
 adheres to a given interface (the word is italicized because Python has no
 explicit notion of interface, by that word we mean a given set of methods must
 be implemented by the Python class):
 
-::
+.. code-block:: python
 
    class SyntheticChildrenProvider:
       def __init__(self, valobj, internal_dict):
          this call should initialize the Python object using valobj as the variable to provide synthetic children for
       def num_children(self):
          this call should return the number of children that you want your object to have
       def get_child_index(self,name):
          this call should return the index of the synthetic child whose name is given as argument

 you return here will most likely be a numeric type (int, float, ...) as its
 value bytes will be used as-if they were the value of the root SBValue proper.
 As a shortcut for this, you can inherit from lldb.SBSyntheticValueProvider, and
 just define get_value as other methods are defaulted in the superclass as
 returning default no-children responses.
 
 If a synthetic child provider supplies a special child named
 ``$$dereference$$`` then it will be used when evaluating ``operator *`` and
-``operator ->`` in the frame variable command and related SB API functions.
+``operator ->`` in the frame variable command and related SB API
+functions. It is possible to declare this synthetic child without
+including it in the range of children displayed by LLDB. For example,
+this subset of a synthetic children provider class would allow the
+synthetic value to be dereferenced without actually showing any
+synthtic children in the UI:
+
+.. code-block:: python
+
+      class SyntheticChildrenProvider:
+          [...]
+          def num_children(self):
+              return 0
+          def get_child_index(self, name):
+              if name == '$$dereference$$':
+                  return 0
+              return -1
+          def get_child_at_index(self, index):
+              if index == 0:
+                  return <valobj resulting from dereference>
+              return None
+
 
 For examples of how synthetic children are created, you are encouraged to look
 at examples/synthetic in the LLDB trunk. Please, be aware that the code in
 those files (except bitfield/) is legacy code and is not maintained. You may
 especially want to begin looking at this example to get a feel for this
 feature, as it is a very easy and well commented example.
 
 The design pattern consistently used in synthetic providers shipping with LLDB

lldb/packages/Python/lldbsuite/test/functionalities/data-formatter/data-formatter-python-synth/TestDataFormatterPythonSynth.py

def setUp(self):
         self.line = line_number('main.cpp', '// Set break point at this line.')
         self.line2 = line_number('main.cpp',
                                  '// Set cast break point at this line.')
         self.line3 = line_number(
             'main.cpp', '// Set second cast break point at this line.')
 
     def data_formatter_commands(self):
         """Test using Python synthetic children provider."""
-        self.runCmd("file " + self.getBuildArtifact("a.out"), CURRENT_EXECUTABLE_SET)
-
-        lldbutil.run_break_set_by_file_and_line(
-            self, "main.cpp", self.line, num_expected_locations=1, loc_exact=True)
-
-        self.runCmd("run", RUN_SUCCEEDED)
-
-        process = self.dbg.GetSelectedTarget().GetProcess()
 
-        # The stop reason of the thread should be breakpoint.
-        self.expect("thread list", STOPPED_DUE_TO_BREAKPOINT,
-                    substrs=['stopped',
-                             'stop reason = breakpoint'])
+        _, process, thread, _ = lldbutil.run_to_line_breakpoint(
+            self, lldb.SBFileSpec("main.cpp"), self.line)
 
         # This is the function to remove the custom formats in order to have a
         # clean slate for the next test case.
         def cleanup():
             self.runCmd('type format clear', check=False)
             self.runCmd('type summary clear', check=False)
             self.runCmd('type filter clear', check=False)
             self.runCmd('type synth clear', check=False)
 
         # Execute the cleanup function during test case tear down.
         self.addTearDownHook(cleanup)
 
         # print the f00_1 variable without a synth
         self.expect("frame variable f00_1",
                     substrs=['a = 1',
                              'b = 2',
                              'r = 34'])
 
         # now set up the synth
         self.runCmd("script from fooSynthProvider import *")
         self.runCmd("type synth add -l fooSynthProvider foo")
+        self.runCmd("type synth add -l wrapfooSynthProvider wrapfoo")
         self.expect("type synthetic list foo", substrs=['fooSynthProvider'])
 
         # note that the value of fake_a depends on target byte order
         if process.GetByteOrder() == lldb.eByteOrderLittle:
             fake_a_val = 0x02000000
         else:
             fake_a_val = 0x00000100
 
def data_formatter_commands(self):
             fake_a_val = 0x0d000000
         else:
             fake_a_val = 0x00000c00
 
         self.expect("frame variable --ptr-depth 1 f00_ptr",
                     substrs=['r = 45',
                              'fake_a = %d' % fake_a_val,
                              'a = 12'])
+        self.expect("frame variable --ptr-depth 1 wrapper",
+                    substrs=['r = 45',
+                             'fake_a = %d' % fake_a_val,
+                             'a = 12'])
 
         # now add a filter.. it should fail
         self.expect("type filter add foo --child b --child j", error=True,
                     substrs=['cannot add'])
 
         # we get the synth again..
         self.expect('frame variable f00_1', matching=False,
                     substrs=['b = 1',
                              'j = 17'])
         self.expect("frame variable --ptr-depth 1 f00_ptr",
                     substrs=['r = 45',
                              'fake_a = %d' % fake_a_val,
                              'a = 12'])
+        self.expect("frame variable --ptr-depth 1 wrapper",
+                    substrs=['r = 45',
+                             'fake_a = %d' % fake_a_val,
+                             'a = 12'])
+
+        # Test that the custom dereference operator for `wrapfoo` works through
+        # the Python API. The synthetic children provider gets queried at
+        # slightly different times in this case.
+        wrapper_var = thread.GetSelectedFrame().FindVariable('wrapper')
+        foo_var = wrapper_var.Dereference()
+        self.assertEqual(foo_var.GetNumChildren(), 3)
+        self.assertEqual(foo_var.GetChildAtIndex(0).GetName(), 'a')
+        self.assertEqual(foo_var.GetChildAtIndex(1).GetName(), 'fake_a')
+        self.assertEqual(foo_var.GetChildAtIndex(2).GetName(), 'r')
 
         # now delete the synth and add the filter
         self.runCmd("type synth delete foo")
+        self.runCmd("type synth delete wrapfoo")
         self.runCmd("type filter add foo --child b --child j")
 
         self.expect('frame variable f00_1',
                     substrs=['b = 2',
                              'j = 18'])
         self.expect("frame variable --ptr-depth 1 f00_ptr", matching=False,
                     substrs=['r = 45',
                              'fake_a = %d' % fake_a_val,
                              'a = 12'])
+        self.expect("frame variable --ptr-depth 1 wrapper", matching=False,
+                    substrs=['r = 45',
+                             'fake_a = %d' % fake_a_val,
+                             'a = 12'])
 
         # now add the synth and it should fail
         self.expect("type synth add -l fooSynthProvider foo", error=True,
                     substrs=['cannot add'])
 
         # check the listing
         self.expect('type synth list', matching=False,
                     substrs=['foo',
def data_formatter_commands(self):
 
         self.expect('frame variable f00_1', matching=False,
                     substrs=['b = 2',
                              'j = 18'])
         self.expect("frame variable --ptr-depth 1 f00_ptr",
                     substrs=['r = 45',
                              'fake_a = %d' % fake_a_val,
                              'a = 12'])
+        self.expect("frame variable --ptr-depth 1 wrapper",
+                    substrs=['r = 45',
+                             'fake_a = %d' % fake_a_val,
+                             'a = 12'])
 
         # check the listing
         self.expect('type synth list',
                     substrs=['foo',
                              'Python class fooSynthProvider'])
         self.expect('type filter list', matching=False,
                     substrs=['foo',
                              '.b',

lldb/packages/Python/lldbsuite/test/functionalities/data-formatter/data-formatter-python-synth/fooSynthProvider.py

def get_child_index(self, name):
         if name == 'a':
             return 0
         if name == 'fake_a':
             return 1
         return 2
 
     def update(self):
         return True
+
+
+class wrapfooSynthProvider:
+
+    def __init__(self, valobj, dict):
+        self.valobj = valobj
+
+    def num_children(self):
+        return 1
+
+    def get_child_at_index(self, index):
+        if index == 0:
+            return self.valobj.GetChildMemberWithName('ptr')
+        if index == 1:
+            return self.valobj.GetChildMemberWithName('ptr').Dereference()
+        return None
+
+    def get_child_index(self, name):
+        if name == 'ptr':
+            return 0
+        if name == '$$dereference$$':
+            return 1
+        return -1
+
+    def update(self):
+        return True

lldb/packages/Python/lldbsuite/test/functionalities/data-formatter/data-formatter-python-synth/main.cpp

 };
 
 struct wrapint
 {
     int x;
     wrapint(int X) : x(X) {}
 };
 
+struct wrapfoo
+{
+    foo *ptr;
+};
+
 int main()
 {
     foo f00_1(1);
     foo *f00_ptr = new foo(12);
-    
+    wrapfoo wrapper{f00_ptr};
     f00_1.a++; // Set break point at this line.
     
     wrapint test_cast('A' +
                256*'B' +
                256*256*'C'+
                256*256*256*'D');
     // Set cast break point at this line.
     test_cast.x = 'Q' +
                  256*'X' +
                  256*256*'T'+
                  256*256*256*'F';
     return 0;     // Set second cast break point at this line.
 }

lldb/source/Core/ValueObject.cpp

if (child_compiler_type && child_byte_size) {
           child_is_base_class, child_is_deref_of_parent, eAddressTypeInvalid,
           language_flags);
     }
   } else if (HasSyntheticValue()) {
     m_deref_valobj =
         GetSyntheticValue()
             ->GetChildMemberWithName(ConstString("$$dereference$$"), true)
             .get();
+  } else if (IsSynthetic()) {
+    m_deref_valobj =
+        GetChildMemberWithName(ConstString("$$dereference$$"), true).get();
   }
 
   if (m_deref_valobj) {
     error.Clear();
     return m_deref_valobj->GetSP();
   } else {
     StreamString strm;
     GetExpressionPath(strm, true);