[lldb] Make callback-based formatter matching available from the CLI.

[jgorbe]

Summary

This change adds a --recognizer-function (-R) to type summary add
and type synth add that allows users to specify that the names in
the command are not type names but python function names.

It also adds an example to lldb/examples, and a section in the data
formatters documentation on how to use recognizer functions.

[labath]

Seems fine to me.

lldb/source/Commands/Options.td

1238

There's a little-known trick to avoid a short version of an option by using a non-printable character here (like "\\x01", see disassemble --force). Given that we don't expect this to be widely used (and that R could also mean Regex), maybe this is the time to use it?

[jingham]

This looks good. The one detail that remains is error handling for the command. You can't provide the --regex option and this matcher at the same time, and it is also an error to have both this matcher function and any arguments in the argument list. We handle the former by judicious use of "option groups" (see the Group(N) entries in the Option.td). The latter you will have to do by hand, checking that if match_type is eFormatterMatchCallback, then if there are any arguments, you should raise an error.

[jgorbe]

You can't provide the --regex option and this matcher at the same time

Thanks for spotting this. I'll get to it.

it is also an error to have both this matcher function and any arguments in the argument list

Not with the code as it is. I've made the new flag have similar semantics to --regex. If I'm not mistaken, with --regex, all the arguments in the argument list are treated as regular expressions instead of type names, and with --recognizer-function all the arguments in the argument list will be treated as recognizer functions instead.

Would you prefer having the --recognizer-function flag take an argument instead and error out if the argument list is not empty? On one hand I can see the argument for that being somewhat more intuitive. On the other hand, making the new flag be "special" (in the sense that it doesn't behave like --regex) makes the command set a little less consistent which IMO is less intuitive. I'm happy to go either way if you have a strong opinion about the way it should work.

[jgorbe]

I'm looking at the option of using a non-printable character for the short flag, and at the same time make --regex and --recognizer-function mutually exclusive using option groups. One problem I see is that the command help gets pretty confusing. Using a non-printable character as the short option name makes the option completely disappear from the "Command Options Usage" summary part of the help.

For example, for disassemble the --force option is defined with Groups[2,3,4,5,7] but there's no indication in the usage summary that --force is only usable in some of the groups:

Command Options Usage:
  disassemble [-bkmr] -s <address-expression> [-A <arch>] [-C <num-lines>] [-e <address-expression>] [-F <disassembly-flavor>] [-P <plugin>]
  disassemble [-bkmr] -s <address-expression> [-A <arch>] [-C <num-lines>] [-c <num-lines>] [-F <disassembly-flavor>] [-P <plugin>]
  disassemble [-bkmr] [-A <arch>] [-C <num-lines>] [-c <num-lines>] [-F <disassembly-flavor>] [-n <function-name>] [-P <plugin>]
  disassemble [-bfkmr] [-A <arch>] [-C <num-lines>] [-c <num-lines>] [-F <disassembly-flavor>] [-P <plugin>]
  disassemble [-bkmpr] [-A <arch>] [-C <num-lines>] [-c <num-lines>] [-F <disassembly-flavor>] [-P <plugin>]
  disassemble [-bklmr] [-A <arch>] [-C <num-lines>] [-F <disassembly-flavor>] [-P <plugin>]
  disassemble [-bkmr] [-a <address-expression>] [-A <arch>] [-C <num-lines>] [-c <num-lines>] [-F <disassembly-flavor>] [-P <plugin>]

---

In the type summary add and type synth add class it would be even worse IMO, because we're now using the groups to enforce two mutually exclusive flags. --regex (-x) is currently accepted everywhere:

type summary add -c [-Oprvx] [-C <boolean>] [-w <name>] <name> [<name> [...]]
type summary add [-ehprvx] -s <summary-string> [-C <boolean>] [-w <name>] [-n <name>] <name> [<name> [...]]
type summary add [-Pehprvx] [-C <boolean>] [-w <name>] [-n <name>] [-F <python-function>] [-o <python-script>] <name> [<name> [...]]

so we need to double the number of groups. Half would have -x and the other half would have -R. But if we don't have a short flag, then we end up with something like this:

type summary add -c [-Oprvx] [-C <boolean>] [-w <name>] <name> [<name> [...]]
type summary add [-ehprvx] -s <summary-string> [-C <boolean>] [-w <name>] [-n <name>] <name> [<name> [...]]
type summary add [-Pehprvx] [-C <boolean>] [-w <name>] [-n <name>] [-F <python-function>] [-o <python-script>] <name> [<name> [...]]
type summary add -c [-Oprv] [-C <boolean>] [-w <name>] <name> [<name> [...]]
type summary add [-ehprv] -s <summary-string> [-C <boolean>] [-w <name>] [-n <name>] <name> [<name> [...]]
type summary add [-Pehprv] [-C <boolean>] [-w <name>] [-n <name>] [-F <python-function>] [-o <python-script>] <name> [<name> [...]]

... where the only visible difference between groups 1-3 and 4-6 is that they don't have the optional -x.

I think a reasonable compromise would be to remove the short -R flag, not use groups to enforce the mutual exclusion with -x, and have some ad-hoc error logic to alert the user if they specify both options at the same time. This way we don't have to duplicate the number of groups just for the sake of an option that will presumably be only very rarely used. I'll give that a try.

[jgorbe]

• Removed -R short option to avoid confusion with regex. Updated doc, test case, and example.
• Added some logic to make --recognizer-function and --regex mutually exclusive. Specifying both now results in an error being reported to the user.
• Rebased on top of current HEAD.

[labath]

In D137000#3897878, @jgorbe wrote:

I'm looking at the option of using a non-printable character for the short flag, and at the same time make --regex and --recognizer-function mutually exclusive using option groups. One problem I see is that the command help gets pretty confusing. Using a non-printable character as the short option name makes the option completely disappear from the "Command Options Usage" summary part of the help.

For example, for disassemble the --force option is defined with Groups[2,3,4,5,7] but there's no indication in the usage summary that --force is only usable in some of the groups:

Hmm.. you're right, I didn't know that. I'll leave it up to you, but personally I wouldn't consider it a blocker, as I think that the way we print our option group help needs an overhaul anyway. I mean, the idea is kinda nice, but after a certain number of options (and groups) it just becomes ridiculous. For example, I'd like to meet the person who can make sense of this:

Command Options Usage:
  breakpoint set [-DHd] -l <linenum> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-u <column>] [-f <filename>] [-m <boolean>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -a <address-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-s <shlib-name>]
  breakpoint set [-DHd] -n <function-name> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -F <fullname> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -S <selector> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -M <method> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -r <regular-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -b <function-name> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-ADHd] -p <regular-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-f <filename>] [-m <boolean>] [-s <shlib-name>] [-X <function-name>]
  breakpoint set [-DHd] -E <source-language> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-h <boolean>] [-w <boolean>]
  breakpoint set [-DHd] -P <python-class> [-k <none>] [-v <none>] [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-f <filename>] [-s <shlib-name>]
  breakpoint set [-DHd] -y <linespec> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-m <boolean>] [-s <shlib-name>] [-K <boolean>]

[jgorbe]

@jingham any comments on https://reviews.llvm.org/D137000#3897162?

[jingham]

It is a bit odd to follow the what the help summary says is a valid option set and then get an error. But this is a corner case, and since you say explicitly that you can't provide both that's probably good enough. Would you mind changing "Incompatible with" to: "Cannot be specified at the same time as". Incompatible isn't precise - does it mean you can't use them both, or that if you do something weird will happen?

Other than that, this is fine. Thanks for working on this.

[jingham]

In D137000#3902217, @labath wrote:

In D137000#3897878, @jgorbe wrote:

I'm looking at the option of using a non-printable character for the short flag, and at the same time make --regex and --recognizer-function mutually exclusive using option groups. One problem I see is that the command help gets pretty confusing. Using a non-printable character as the short option name makes the option completely disappear from the "Command Options Usage" summary part of the help.

For example, for disassemble the --force option is defined with Groups[2,3,4,5,7] but there's no indication in the usage summary that --force is only usable in some of the groups:

Hmm.. you're right, I didn't know that. I'll leave it up to you, but personally I wouldn't consider it a blocker, as I think that the way we print our option group help needs an overhaul anyway. I mean, the idea is kinda nice, but after a certain number of options (and groups) it just becomes ridiculous. For example, I'd like to meet the person who can make sense of this:

Command Options Usage:
  breakpoint set [-DHd] -l <linenum> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-u <column>] [-f <filename>] [-m <boolean>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -a <address-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-s <shlib-name>]
  breakpoint set [-DHd] -n <function-name> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -F <fullname> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -S <selector> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -M <method> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -r <regular-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-DHd] -b <function-name> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-f <filename>] [-L <source-language>] [-s <shlib-name>] [-K <boolean>]
  breakpoint set [-ADHd] -p <regular-expression> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-f <filename>] [-m <boolean>] [-s <shlib-name>] [-X <function-name>]
  breakpoint set [-DHd] -E <source-language> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-h <boolean>] [-w <boolean>]
  breakpoint set [-DHd] -P <python-class> [-k <none>] [-v <none>] [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-N <breakpoint-name>] [-f <filename>] [-s <shlib-name>]
  breakpoint set [-DHd] -y <linespec> [-G <boolean>] [-C <command>] [-c <expr>] [-i <count>] [-o <boolean>] [-q <queue-name>] [-t <thread-id>] [-x <thread-index>] [-T <thread-name>] [-R <address>] [-N <breakpoint-name>] [-m <boolean>] [-s <shlib-name>] [-K <boolean>]

If I were starting over, I would make "break set" be a multiword command with sub-commands for all the primary specification operations (break set file, break set name etc.) We could use unique first letters for all the actual operations, so this would actually be LESS typing by one dash, and would allow for better documentation of the shared options. But I don't think we can get away with that at this point.

This display while noisy is the only way you can see all the kinds of breakpoint setting operations, so we really have to have something like this, and it should be fairly reliable... It would also be nice if help also understood options, so for instance:help break set -a should only show you the variants that include that option.

[jgorbe]

In D137000#3915943, @jingham wrote:

It is a bit odd to follow the what the help summary says is a valid option set and then get an error. But this is a corner case, and since you say explicitly that you can't provide both that's probably good enough. Would you mind changing "Incompatible with" to: "Cannot be specified at the same time as". Incompatible isn't precise - does it mean you can't use them both, or that if you do something weird will happen?

After following Pavel's suggestion to remove the short flag it doesn't show up at all in the help summary, so the help summary still shows a valid option set. It just lists the long flag for the new option in the detailed list after the summary, like this:

Command Options Usage:
  type summary add -c [-Oprvx] [-C <boolean>] [-w <name>] <name> [<name> [...]]
  type summary add [-ehprvx] -s <summary-string> [-C <boolean>] [-w <name>] [-n <name>] <name> [<name> [...]]
  type summary add [-Pehprvx] [-C <boolean>] [-w <name>] [-n <name>] [-F <python-function>] [-o <python-script>] <name> [<name> [...]]

       --recognizer-function
            The names in the argument list are actually the names of python functions that decide whether to use this summary for any given type. Cannot be specified at the same time as --regex (-x).

Other than that, this is fine. Thanks for working on this.

Thank you both for helping me land this feature! :)

[jgorbe]

• Clarified help text for --recognizer-function as suggested by reviewer. Instead of "Incompatible with --regex (-x)." now it says "Cannot be specified at the same time as --regex (-x)."
• Rebased on top of current HEAD.

lldb/docs/use/variable.rst

::
    (lldb) type filter add Foobar --child B --child H --child Q
    (lldb) frame variable a_foobar
    (Foobar) a_foobar = {
       (int) B = 1
       (char) H = 'H'
       (std::string) Q = "Hello world"
    }
 
+Callback-based type matching
+----------------------------
+
+Even though regular expression matching works well for the vast majority of data
+formatters (you normally know the name of the type you're writing a formatter
+for), there are some cases where it's useful to look at the type before deciding
+what formatter to apply.
+
+As an example scenario, imagine we have a code generator that produces some
+classes that inherit from a common ``GeneratedObject`` class, and we have a
+summary function and a synthetic child provider that work for all
+``GeneratedObject`` instances (they all follow the same pattern). However, there
+is no common pattern in the name of these classes, so we can't register the
+formatter neither by name nor by regular expression.
+
+In that case, you can write a recognizer function like this:
+
+::
+
+   def is_generated_object(sbtype, internal_dict):
+     for base in sbtype.get_bases_array():
+       if base.GetName() == "GeneratedObject"
+         return True
+     return False
+
+And pass this function to ``type summary add`` and ``type synthetic add`` using
+the flag ``--recognizer-function``.
+
+::
+
+   (lldb) type summary add --expand --python-function my_summary_function --recognizer-function is_generated_object
+   (lldb) type synthetic add --python-class my_child_provider --recognizer-function is_generated_object
+
 Objective-C Dynamic Type Discovery
 ----------------------------------
 
 When doing Objective-C development, you may notice that some of your variables
 come out as of type id (for instance, items extracted from NSArray). By
 default, LLDB will not show you the real type of the object. it can actually
 dynamically discover the type of an Objective-C variable, much like the runtime
 itself does when invoking a selector. In order to be shown the result of that

lldb/examples/synthetic/recognizer_function/example.py

+# Formatters for classes that derive from Message.
+#
+# Usage:
+#   command script import ./example.py
+#   type summary add --expand --recognizer-function --python-function example.message_summary example.is_message_type
+#   type synth add --recognizer-function --python-class example.MessageChildProvider example.is_message_type
+
+import sys
+
+def is_message_type(t, internal_dict):
+  for base in t.get_bases_array():
+    if base.GetName() == "Message":
+      return True
+  return False
+
+def message_summary(value, internal_dict):
+  # Could have used a summary string as well. All the work is done by the child
+  # provider.
+  return "Message"
+
+class MessageChildProvider:
+  def __init__(self, value, internal_dict):
+    self.value = value
+    self.synthetic_children = self._analyze_children(value)
+
+  def has_children(self):
+    return self.num_children() > 0
+
+  def num_children(self):
+    return len(self.synthetic_children)
+
+  def get_child_index(self, name):
+    for index, child in enumerate(self.synthetic_children):
+      if child.GetName() == name:
+        return index
+    return None
+
+  def get_child_at_index(self, index):
+    return self.synthetic_children[index]
+
+  def _rename_sbvalue(self, value):
+    # We want to display the field with its original name without a trailing
+    # underscore. So we create a new SBValue with the same type and address but
+    # a different name.
+    name = value.GetName()
+    assert name.endswith("_")
+    new_name = name[:-1]
+    return value.CreateValueFromAddress(new_name, value.GetLoadAddress(),
+                                        value.GetType())
+
+  def _analyze_children(self, value):
+    result = []
+    for i in range(value.GetNumChildren()):
+      child = value.GetChildAtIndex(i)
+      child_name = child.GetName()
+      if child_name.startswith("_"):
+        continue  # Internal field, skip
+      # Normal field. Check presence bit.
+      presence_bit = value.GetChildMemberWithName("_has_" + child_name)
+      if presence_bit.GetValueAsUnsigned() != 0:
+        result.append(self._rename_sbvalue(child))
+    return result
+

lldb/examples/synthetic/recognizer_function/lldb-commands

+command script import ./example.py
+type summary add --expand --recognizer-function --python-function example.message_summary example.is_message_type
+type synth add --recognizer-function --python-class example.MessageChildProvider example.is_message_type
+b program.cpp:112
+r
+p customer
+p order

lldb/examples/synthetic/recognizer_function/program.cpp

+// Example program for matching summary functions and synthetic child providers.
+//
+// The classes here simulate code generated by a serialization tool like, for
+// example, protocol buffers. But the actual "generated" class layout is
+// extremely naive to simplify the example.
+//
+// The idea is that we want to have generic formatters for a bunch of message
+// classes, because they are all generated following common patterns, but the
+// matching can't be based in the type name, because it can be anything.
+
+#include <string>
+
+class Message {
+  // Dummy method definitions to illustrate a possible generic message API.
+  std::string serialize() { return "TODO"; }
+  Message* deserialize() {
+    return nullptr;  // TODO.
+  }
+};
+
+// This class could have been generated from a description like this. Assume
+// fields are always optional, for simplicity (e.g. we don't care during
+// serialization if a Customer has a name or not, we're just moving data around
+// and validation happens elsewhere).
+//
+// message Customer {
+//   string name;
+//   int age;
+//   string address;
+// }
+class Customer : public Message {
+ private:
+  int _internal_bookkeeping_bits_;
+
+  // Presence bits. They are true if the field has been set.
+  bool _has_name_ = false;
+  bool _has_age_ = false;
+  bool _has_address_ = false;
+
+  // Actual field data.
+  std::string name_;
+  int age_;
+  std::string address_;
+
+ public:
+  // Getters and setters.
+  bool has_name() { return _has_name_; }
+  bool has_age() { return _has_age_; }
+  bool has_address() { return _has_address_; }
+
+  std::string name() { return name_; }
+  int age() { return age_; }
+  std::string address() { return address_; }
+
+  void set_name(std::string name) {
+    name_ = name;
+    _has_name_ = true;
+  }
+  void set_age(int age) {
+    age_ = age;
+    _has_age_ = true;
+  }
+  void set_address(std::string address) {
+    address_ = address;
+    _has_address_ = true;
+  }
+};
+
+// message ProductOrder {
+//   string product_name;
+//   int amount;
+// }
+class ProductOrder : public Message {
+ private:
+  int _internal_bookkeeping_bits_;
+
+  // Presence bits. They are true if the field has been set.
+  bool _has_product_name_ = false;
+  bool _has_amount_ = false;
+
+  // Actual field data.
+  std::string product_name_;
+  int amount_;
+
+ public:
+  // Getters and setters.
+  bool has_product_name() { return _has_product_name_; }
+  bool has_amount() { return _has_amount_; }
+
+  std::string get_product_name() { return product_name_; }
+  int get_amount() { return amount_; }
+
+  void set_product_name(std::string product_name) {
+    product_name_ = product_name;
+    _has_product_name_ = true;
+  }
+  void set_amount(int amount) {
+    amount_ = amount;
+    _has_amount_ = true;
+  }
+};
+
+int main(int argc, char **argv) {
+  Customer customer;
+  customer.set_name("C. Ustomer");
+  customer.set_address("123 Fake St.");
+  // no age, so we can check absent fields get omitted.
+
+  ProductOrder order;
+  order.set_product_name("widget");
+  order.set_amount(100);
+  return 0;  // break here.
+}
+

lldb/source/Commands/CommandObjectType.cpp

 
 using namespace lldb;
 using namespace lldb_private;
 
 class ScriptAddOptions {
 public:
   TypeSummaryImpl::Flags m_flags;
   StringList m_target_types;
-  bool m_regex;
+  FormatterMatchType m_match_type;
   ConstString m_name;
   std::string m_category;
 
-  ScriptAddOptions(const TypeSummaryImpl::Flags &flags, bool regx,
-                   ConstString name, std::string catg)
-      : m_flags(flags), m_regex(regx), m_name(name), m_category(catg) {}
+  ScriptAddOptions(const TypeSummaryImpl::Flags &flags,
+                   FormatterMatchType match_type, ConstString name,
+                   std::string catg)
+      : m_flags(flags), m_match_type(match_type), m_name(name),
+        m_category(catg) {}
 
   typedef std::shared_ptr<ScriptAddOptions> SharedPointer;
 };
 
 class SynthAddOptions {
 public:
   bool m_skip_pointers;
   bool m_skip_references;
   bool m_cascade;
-  bool m_regex;
+  FormatterMatchType m_match_type;
   StringList m_target_types;
   std::string m_category;
 
-  SynthAddOptions(bool sptr, bool sref, bool casc, bool regx, std::string catg)
+  SynthAddOptions(bool sptr, bool sref, bool casc,
+                  FormatterMatchType match_type, std::string catg)
       : m_skip_pointers(sptr), m_skip_references(sref), m_cascade(casc),
-        m_regex(regx), m_category(catg) {}
+        m_match_type(match_type), m_category(catg) {}
 
   typedef std::shared_ptr<SynthAddOptions> SharedPointer;
 };
 
 static bool WarnOnPotentialUnquotedUnsignedType(Args &command,
                                                 CommandReturnObject &result) {
   if (command.empty())
     return false;
public:
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
       return llvm::makeArrayRef(g_type_summary_add_options);
     }
 
     // Instance variables to hold the values for command options.
 
     TypeSummaryImpl::Flags m_flags;
-    bool m_regex = false;
+    FormatterMatchType m_match_type = eFormatterMatchExact;
     std::string m_format_string;
     ConstString m_name;
     std::string m_python_script;
     std::string m_python_function;
     bool m_is_add_script = false;
     std::string m_category;
   };
 
   CommandOptions m_options;
 
   Options *GetOptions() override { return &m_options; }
 
   bool Execute_ScriptSummary(Args &command, CommandReturnObject &result);
 
   bool Execute_StringSummary(Args &command, CommandReturnObject &result);
 
 public:
-  enum SummaryFormatType { eRegularSummary, eRegexSummary, eNamedSummary };
-
   CommandObjectTypeSummaryAdd(CommandInterpreter &interpreter);
 
   ~CommandObjectTypeSummaryAdd() override = default;
 
   void IOHandlerActivated(IOHandler &io_handler, bool interactive) override {
     static const char *g_summary_addreader_instructions =
         "Enter your Python command(s). Type 'DONE' to end.\n"
         "def function (valobj,internal_dict):\n"
if (interpreter) {
                 TypeSummaryImplSP script_format;
                 script_format = std::make_shared<ScriptSummaryFormat>(
                     options->m_flags, funct_name_str.c_str(),
                     lines.CopyList("    ").c_str());
 
                 Status error;
 
                 for (const std::string &type_name : options->m_target_types) {
-                  CommandObjectTypeSummaryAdd::AddSummary(
-                      ConstString(type_name), script_format,
-                      (options->m_regex
-                           ? CommandObjectTypeSummaryAdd::eRegexSummary
-                           : CommandObjectTypeSummaryAdd::eRegularSummary),
-                      options->m_category, &error);
+                  AddSummary(ConstString(type_name), script_format,
+                             options->m_match_type, options->m_category,
+                             &error);
                   if (error.Fail()) {
                     error_sp->Printf("error: %s", error.AsCString());
                     error_sp->Flush();
                   }
                 }
 
                 if (options->m_name) {
-                  CommandObjectTypeSummaryAdd::AddSummary(
-                      options->m_name, script_format,
-                      CommandObjectTypeSummaryAdd::eNamedSummary,
-                      options->m_category, &error);
+                  CommandObjectTypeSummaryAdd::AddNamedSummary(
+                      options->m_name, script_format, &error);
                   if (error.Fail()) {
-                    CommandObjectTypeSummaryAdd::AddSummary(
-                        options->m_name, script_format,
-                        CommandObjectTypeSummaryAdd::eNamedSummary,
-                        options->m_category, &error);
+                    CommandObjectTypeSummaryAdd::AddNamedSummary(
+                        options->m_name, script_format, &error);
                     if (error.Fail()) {
                       error_sp->Printf("error: %s", error.AsCString());
                       error_sp->Flush();
                     }
                   } else {
                     error_sp->Printf("error: %s", error.AsCString());
                     error_sp->Flush();
                   }
if (interpreter) {
       error_sp->Printf(
           "error: script interpreter missing, didn't add python command.\n");
       error_sp->Flush();
     }
 #endif
     io_handler.SetIsDone(true);
   }
 
-  static bool AddSummary(ConstString type_name, lldb::TypeSummaryImplSP entry,
-                         SummaryFormatType type, std::string category,
-                         Status *error = nullptr);
+  bool AddSummary(ConstString type_name, lldb::TypeSummaryImplSP entry,
+                  FormatterMatchType match_type, std::string category,
+                  Status *error = nullptr);
+
+  bool AddNamedSummary(ConstString summary_name, lldb::TypeSummaryImplSP entry,
 
 protected:
   bool DoExecute(Args &command, CommandReturnObject &result) override;
 };
 
 static const char *g_synth_addreader_instructions =
     "Enter your Python command(s). Type 'DONE' to end.\n"
     "You must define a Python class with these methods:\n"
Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
         break;
       case 'r':
         m_skip_references = true;
         break;
       case 'w':
         m_category = std::string(option_arg);
         break;
       case 'x':
-        m_regex = true;
+        if (m_match_type == eFormatterMatchCallback)
+          error.SetErrorString(
+              "can't use --regex and --recognizer-function at the same time");
+        else
+          m_match_type = eFormatterMatchRegex;
+        break;
+      case '\x01':
+        if (m_match_type == eFormatterMatchRegex)
+          error.SetErrorString(
+              "can't use --regex and --recognizer-function at the same time");
+        else
+          m_match_type = eFormatterMatchCallback;
         break;
       default:
         llvm_unreachable("Unimplemented option");
       }
 
       return error;
     }
 
     void OptionParsingStarting(ExecutionContext *execution_context) override {
       m_cascade = true;
       m_class_name = "";
       m_skip_pointers = false;
       m_skip_references = false;
       m_category = "default";
       is_class_based = false;
       handwrite_python = false;
-      m_regex = false;
+      m_match_type = eFormatterMatchExact;
     }
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
       return llvm::makeArrayRef(g_type_synth_add_options);
     }
 
     // Instance variables to hold the values for command options.
 
     bool m_cascade;
     bool m_skip_references;
     bool m_skip_pointers;
     std::string m_class_name;
     bool m_input_python;
     std::string m_category;
     bool is_class_based;
     bool handwrite_python;
-    bool m_regex;
+    FormatterMatchType m_match_type;
   };
 
   CommandOptions m_options;
 
   Options *GetOptions() override { return &m_options; }
 
   bool Execute_HandwritePython(Args &command, CommandReturnObject &result);
 
if (interpreter) {
                 lldb::TypeCategoryImplSP category;
                 DataVisualization::Categories::GetCategory(
                     ConstString(options->m_category.c_str()), category);
 
                 Status error;
 
                 for (const std::string &type_name : options->m_target_types) {
                   if (!type_name.empty()) {
-                    if (!CommandObjectTypeSynthAdd::AddSynth(
-                            ConstString(type_name), synth_provider,
-                            options->m_regex
-                                ? CommandObjectTypeSynthAdd::eRegexSynth
-                                : CommandObjectTypeSynthAdd::eRegularSynth,
-                            options->m_category, &error)) {
+                    if (AddSynth(ConstString(type_name), synth_provider,
+                                 options->m_match_type, options->m_category,
+                                 &error)) {
                       error_sp->Printf("error: %s\n", error.AsCString());
                       error_sp->Flush();
                       break;
                     }
                   } else {
                     error_sp->Printf("error: invalid type name.\n");
                     error_sp->Flush();
                     break;
if (interpreter) {
       error_sp->Flush();
     }
 
 #endif
     io_handler.SetIsDone(true);
   }
 
 public:
-  enum SynthFormatType { eRegularSynth, eRegexSynth };
-
   CommandObjectTypeSynthAdd(CommandInterpreter &interpreter);
 
   ~CommandObjectTypeSynthAdd() override = default;
 
-  static bool AddSynth(ConstString type_name, lldb::SyntheticChildrenSP entry,
-                       SynthFormatType type, std::string category_name,
-                       Status *error);
+  bool AddSynth(ConstString type_name, lldb::SyntheticChildrenSP entry,
+                FormatterMatchType match_type, std::string category_name,
 };
 
 // CommandObjectTypeFormatAdd
 
 #define LLDB_OPTIONS_type_format_add
 #include "CommandOptions.inc"
 
 class CommandObjectTypeFormatAdd : public CommandObjectParsed {
case 's':
     break;
   case 'p':
     m_flags.SetSkipPointers(true);
     break;
   case 'r':
     m_flags.SetSkipReferences(true);
     break;
   case 'x':
-    m_regex = true;
+    if (m_match_type == eFormatterMatchCallback)
+      error.SetErrorString(
+          "can't use --regex and --recognizer-function at the same time");
+    else
+      m_match_type = eFormatterMatchRegex;
+    break;
+  case '\x01':
+    if (m_match_type == eFormatterMatchRegex)
+      error.SetErrorString(
+          "can't use --regex and --recognizer-function at the same time");
+    else
+      m_match_type = eFormatterMatchCallback;
     break;
   case 'n':
     m_name.SetString(option_arg);
     break;
   case 'o':
     m_python_script = std::string(option_arg);
     m_is_add_script = true;
     break;

 void CommandObjectTypeSummaryAdd::CommandOptions::OptionParsingStarting(
     ExecutionContext *execution_context) {
   m_flags.Clear().SetCascades().SetDontShowChildren().SetDontShowValue(false);
   m_flags.SetShowMembersOneLiner(false)
       .SetSkipPointers(false)
       .SetSkipReferences(false)
       .SetHideItemNames(false);
 
-  m_regex = false;
+  m_match_type = eFormatterMatchExact;
   m_name.Clear();
   m_python_script = "";
   m_python_function = "";
   m_format_string = "";
   m_is_add_script = false;
   m_category = "default";
 }
 
if (!m_options.m_python_function
 
     std::string code = "    " + m_options.m_python_script;
 
     script_format = std::make_shared<ScriptSummaryFormat>(
         m_options.m_flags, funct_name_str.c_str(), code.c_str());
   } else {
     // Use an IOHandler to grab Python code from the user
     auto options = std::make_unique<ScriptAddOptions>(
-        m_options.m_flags, m_options.m_regex, m_options.m_name,
+        m_options.m_flags, m_options.m_match_type, m_options.m_name,
         m_options.m_category);
 
     for (auto &entry : command.entries()) {
       if (entry.ref().empty()) {
         result.AppendError("empty typenames not allowed");
         return false;
       }
 
bool CommandObjectTypeSummaryAdd::Execute_ScriptSummary(
   }
 
   // if I am here, script_format must point to something good, so I can add
   // that as a script summary to all interested parties
 
   Status error;
 
   for (auto &entry : command.entries()) {
-    CommandObjectTypeSummaryAdd::AddSummary(
-        ConstString(entry.ref()), script_format,
-        (m_options.m_regex ? eRegexSummary : eRegularSummary),
+    AddSummary(ConstString(entry.ref()), script_format, m_options.m_match_type,
                m_options.m_category, &error);
     if (error.Fail()) {
       result.AppendError(error.AsCString());
       return false;
     }
   }
 
   if (m_options.m_name) {
-    AddSummary(m_options.m_name, script_format, eNamedSummary,
-               m_options.m_category, &error);
+    AddNamedSummary(m_options.m_name, script_format, &error);
     if (error.Fail()) {
       result.AppendError(error.AsCString());
       result.AppendError("added to types, but not given a name");
       return false;
     }
   }
 
   return result.Succeeded();
bool CommandObjectTypeSummaryAdd::Execute_StringSummary(
   Status error;
   for (auto &arg_entry : command.entries()) {
     if (arg_entry.ref().empty()) {
       result.AppendError("empty typenames not allowed");
       return false;
     }
     ConstString typeCS(arg_entry.ref());
 
-    AddSummary(typeCS, entry,
-               (m_options.m_regex ? eRegexSummary : eRegularSummary),
-               m_options.m_category, &error);
+    AddSummary(typeCS, entry, m_options.m_match_type, m_options.m_category,
+               &error);
 
     if (error.Fail()) {
       result.AppendError(error.AsCString());
       return false;
     }
   }
 
   if (m_options.m_name) {
-    AddSummary(m_options.m_name, entry, eNamedSummary, m_options.m_category,
-               &error);
+    AddNamedSummary(m_options.m_name, entry, &error);
     if (error.Fail()) {
       result.AppendError(error.AsCString());
       result.AppendError("added to types, but not given a name");
       return false;
     }
   }
 
   result.SetStatus(eReturnStatusSuccessFinishNoResult);
if (type_name_ref.endswith("[]")) {
     else
       type_name_str.append("\\[[0-9]+\\]");
     type_name.SetCString(type_name_str.c_str());
     return true;
   }
   return false;
 }
 
-bool CommandObjectTypeSummaryAdd::AddSummary(ConstString type_name,
+bool CommandObjectTypeSummaryAdd::AddNamedSummary(ConstString summary_name,
                                                   TypeSummaryImplSP entry,
-                                             SummaryFormatType type,
-                                             std::string category_name,
                                                   Status *error) {
-
-  // Named summaries are a special case, they exist in their own map in the
-  // FormatManager, outside of any categories.
-  if (type == eNamedSummary) {
-    // system named summaries do not exist (yet?)
-    DataVisualization::NamedSummaryFormats::Add(type_name, entry);
-    return true;
-  }
+  DataVisualization::NamedSummaryFormats::Add(summary_name, entry);
 
+bool CommandObjectTypeSummaryAdd::AddSummary(ConstString type_name,
+                                             TypeSummaryImplSP entry,
+                                             FormatterMatchType match_type,
+                                             std::string category_name,
+                                             Status *error) {
   lldb::TypeCategoryImplSP category;
   DataVisualization::Categories::GetCategory(ConstString(category_name.c_str()),
                                              category);
 
-  if (type == eRegularSummary) {
+  if (match_type == eFormatterMatchExact) {
     if (FixArrayTypeNameWithRegex(type_name))
-      type = eRegexSummary;
+      match_type = eFormatterMatchRegex;
   }
 
-  FormatterMatchType match_type = eFormatterMatchExact;
-  if (type == eRegexSummary) {
+  if (match_type == eFormatterMatchRegex) {
     match_type = eFormatterMatchRegex;
     RegularExpression typeRX(type_name.GetStringRef());
     if (!typeRX.IsValid()) {
       if (error)
         error->SetErrorString(
             "regex format error (maybe this is not really a regex?)");
       return false;
     }
   }
+
+  if (match_type == eFormatterMatchCallback) {
+    const char *function_name = type_name.AsCString();
+    ScriptInterpreter *interpreter = GetDebugger().GetScriptInterpreter();
+    if (interpreter && !interpreter->CheckObjectExists(function_name)) {
+      error->SetErrorStringWithFormat(
+          "The provided recognizer function \"%s\" does not exist - "
+          "please define it before attempting to use this summary.\n",
+          function_name);
+      return false;
+    }
+  }
   category->AddTypeSummary(type_name.GetStringRef(), match_type, entry);
   return true;
 }
 
 // CommandObjectTypeSummaryDelete
 
 class CommandObjectTypeSummaryDelete : public CommandObjectTypeFormatterDelete {
 public:
CommandObjectTypeSynthClear(CommandInterpreter &interpreter)
             interpreter, eFormatCategoryItemSynth, "type synthetic clear",
             "Delete all existing synthetic providers.") {}
 };
 
 bool CommandObjectTypeSynthAdd::Execute_HandwritePython(
     Args &command, CommandReturnObject &result) {
   auto options = std::make_unique<SynthAddOptions>(
       m_options.m_skip_pointers, m_options.m_skip_references,
-      m_options.m_cascade, m_options.m_regex, m_options.m_category);
+      m_options.m_cascade, m_options.m_match_type, m_options.m_category);
 
   for (auto &entry : command.entries()) {
     if (entry.ref().empty()) {
       result.AppendError("empty typenames not allowed");
       return false;
     }
 
     options->m_target_types << std::string(entry.ref());
bool CommandObjectTypeSynthAdd::Execute_PythonClass(
 
   for (auto &arg_entry : command.entries()) {
     if (arg_entry.ref().empty()) {
       result.AppendError("empty typenames not allowed");
       return false;
     }
 
     ConstString typeCS(arg_entry.ref());
-    if (!AddSynth(typeCS, entry,
-                  m_options.m_regex ? eRegexSynth : eRegularSynth,
-                  m_options.m_category, &error)) {
+    if (!AddSynth(typeCS, entry, m_options.m_match_type, m_options.m_category,
+                  &error)) {
       result.AppendError(error.AsCString());
       return false;
     }
   }
 
   result.SetStatus(eReturnStatusSuccessFinishNoResult);
   return result.Succeeded();
 }
CommandObjectTypeSynthAdd::CommandObjectTypeSynthAdd(
 
   type_arg.push_back(type_style_arg);
 
   m_arguments.push_back(type_arg);
 }
 
 bool CommandObjectTypeSynthAdd::AddSynth(ConstString type_name,
                                          SyntheticChildrenSP entry,
-                                         SynthFormatType type,
+                                         FormatterMatchType match_type,
                                          std::string category_name,
                                          Status *error) {
   lldb::TypeCategoryImplSP category;
   DataVisualization::Categories::GetCategory(ConstString(category_name.c_str()),
                                              category);
 
-  if (type == eRegularSynth) {
+  if (match_type == eFormatterMatchExact) {
     if (FixArrayTypeNameWithRegex(type_name))
-      type = eRegexSynth;
+      match_type = eFormatterMatchRegex;
   }
 
   // Only check for conflicting filters in the same category if `type_name` is
   // an actual type name. Matching a regex string against registered regexes
   // doesn't work.
-  if (type == eRegularSynth) {
+  if (match_type == eFormatterMatchExact) {
     // It's not generally possible to get a type object here. For example, this
     // command can be run before loading any binaries. Do just a best-effort
     // name-based lookup here to try to prevent conflicts.
     FormattersMatchCandidate candidate_type(type_name, nullptr, TypeImpl(),
                                             FormattersMatchCandidate::Flags());
     if (category->AnyMatches(candidate_type, eFormatCategoryItemFilter,
                              false)) {
       if (error)
         error->SetErrorStringWithFormat("cannot add synthetic for type %s when "
                                         "filter is defined in same category!",
                                         type_name.AsCString());
       return false;
     }
   }
 
-  FormatterMatchType match_type = eFormatterMatchExact;
-  if (type == eRegexSynth) {
-    match_type = eFormatterMatchRegex;
+  if (match_type == eFormatterMatchRegex) {
     RegularExpression typeRX(type_name.GetStringRef());
     if (!typeRX.IsValid()) {
       if (error)
         error->SetErrorString(
             "regex format error (maybe this is not really a regex?)");
       return false;
     }
   }
 
+  if (match_type == eFormatterMatchCallback) {
+    const char *function_name = type_name.AsCString();
+    ScriptInterpreter *interpreter = GetDebugger().GetScriptInterpreter();
+    if (interpreter && !interpreter->CheckObjectExists(function_name)) {
+      error->SetErrorStringWithFormat(
+          "The provided recognizer function \"%s\" does not exist - "
+          "please define it before attempting to use this summary.\n",
+          function_name);
+      return false;
+    }
+  }
+
   category->AddTypeSynthetic(type_name.GetStringRef(), match_type, entry);
   return true;
 }
 
 #endif
 #define LLDB_OPTIONS_type_filter_add
 #include "CommandOptions.inc"
 

lldb/source/Commands/Options.td

let Command = "type summary add" in {
   def type_summary_add_no_value : Option<"no-value", "v">,
     Desc<"Don't show the value, just show the summary, for this type.">;
   def type_summary_add_skip_pointers : Option<"skip-pointers", "p">,
     Desc<"Don't use this format for pointers-to-type objects.">;
   def type_summary_add_skip_references : Option<"skip-references", "r">,
     Desc<"Don't use this format for references-to-type objects.">;
   def type_summary_add_regex : Option<"regex", "x">,
     Desc<"Type names are actually regular expressions.">;
+  def type_summary_add_recognizer_function :
+    Option<"recognizer-function", "\\x01">,
+    Desc<"The names in the argument list are actually the names of python "
+    "functions that decide whether to use this summary for any given type. "
+    "Cannot be specified at the same time as --regex (-x).">;
   def type_summary_add_inline_children : Option<"inline-children", "c">,
     Group<1>, Required,
     Desc<"If true, inline all child values into summary string.">;
   def type_summary_add_omit_names : Option<"omit-names", "O">, Group<1>,
     Desc<"If true, omit value names in the summary display.">;
   def type_summary_add_summary_string : Option<"summary-string", "s">, Group<2>,
     Arg<"SummaryString">, Required,
     Desc<"Summary string used to display text and object contents.">;
let Command = "type synth add" in {
   def type_synth_add_python_class : Option<"python-class", "l">, Group<2>,
     Arg<"PythonClass">,
     Desc<"Use this Python class to produce synthetic children.">;
   def type_synth_add_input_python : Option<"input-python", "P">, Group<3>,
     Desc<"Type Python code to generate a class that provides synthetic "
     "children.">;
   def type_synth_add_regex : Option<"regex", "x">,
     Desc<"Type names are actually regular expressions.">;
+  def type_synth_add_recognizer_function :
+    Option<"recognizer-function", "\\x01">,
+    Desc<"The names in the argument list are actually the names of python "
+    "functions that decide whether to use this summary for any given type. "
+    "Cannot be specified at the same time as --regex (-x).">;
 }
 
 let Command = "type format add" in {
   def type_format_add_category : Option<"category", "w">, Arg<"Name">,
     Desc<"Add this to the given category instead of the default one.">;
   def type_format_add_cascade : Option<"cascade", "C">, Arg<"Boolean">,
     Desc<"If true, cascade through typedef chains.">;
   def type_format_add_skip_pointers : Option<"skip-pointers", "p">,

lldb/test/API/functionalities/data-formatter/callback-matching/TestDataFormatterCallbackMatching.py

 class PythonSynthDataFormatterTestCase(TestBase):
 
     def setUp(self):
         # Call super's setUp().
         TestBase.setUp(self)
         # Find the line number to break at.
         self.line = line_number('main.cpp', '// Set break point at this line.')
 
-    def test_callback_matchers(self):
+    def test_callback_matchers_api_registration(self):
         """Test data formatter commands."""
         self.build()
 
         _, process, thread, _ = lldbutil.run_to_line_breakpoint(
             self, lldb.SBFileSpec("main.cpp"), self.line)
 
         # Print derived without a formatter.
         self.expect("frame variable derived",
                     substrs=['x = 2222',
                              'y = 3333'])
 
         # now set up a summary function that uses a python callback to match
         # classes that derive from `Base`.
         self.runCmd("command script import --allow-reload ./formatters_with_callback.py")
+        self.runCmd("script formatters_with_callback.register_formatters(lldb.debugger)")
 
         # Now `derived` should use our callback summary + synthetic children.
         self.expect("frame variable derived",
                     substrs=['hello from callback summary',
                              'synthetic_child = 9999'])
 
         # But not other classes.
         self.expect("frame variable base", matching=False,
                     substrs=['hello from callback summary'])
         self.expect("frame variable base",
                     substrs=['x = 1111'])
 
         self.expect("frame variable nd", matching=False,
                     substrs=['hello from callback summary'])
         self.expect("frame variable nd",
                     substrs=['z = 4444'])
+
+    def test_callback_matchers_cli_registration(self):
+        """Test data formatter commands."""
+        self.build()
+
+        _, process, thread, _ = lldbutil.run_to_line_breakpoint(
+            self, lldb.SBFileSpec("main.cpp"), self.line)
+
+        # Print derived without a formatter.
+        self.expect("frame variable derived",
+                    substrs=['x = 2222',
+                             'y = 3333'])
+
+        # now set up a summary function that uses a python callback to match
+        # classes that derive from `Base`.
+        self.runCmd("command script import --allow-reload ./formatters_with_callback.py")
+        self.runCmd("type summary add -e -s 'hello from callback summary' "
+                    "--recognizer-function formatters_with_callback.derives_from_base")
+        self.runCmd("type synth add -l formatters_with_callback.SynthProvider "
+                    "--recognizer-function formatters_with_callback.derives_from_base")
+
+        # Now `derived` should use our callback summary + synthetic children.
+        self.expect("frame variable derived",
+                    substrs=['hello from callback summary',
+                             'synthetic_child = 9999'])
+
+        # But not other classes.
+        self.expect("frame variable base", matching=False,
+                    substrs=['hello from callback summary'])
+        self.expect("frame variable base",
+                    substrs=['x = 1111'])
+
+        self.expect("frame variable nd", matching=False,
+                    substrs=['hello from callback summary'])
+        self.expect("frame variable nd",
+                    substrs=['z = 4444'])
+

lldb/test/API/functionalities/data-formatter/callback-matching/formatters_with_callback.py

class SynthProvider:
 
     def get_child_at_index(self, index):
         if index == 0:
             return self.valobj.CreateValueFromExpression("synthetic_child",
                                                          "9999")
         return None
 
 
-def __lldb_init_module(debugger, dict):
+def register_formatters(debugger):
     cat = debugger.CreateCategory("callback_formatters")
     cat.AddTypeSummary(
         lldb.SBTypeNameSpecifier("formatters_with_callback.derives_from_base",
                                  lldb.eFormatterMatchCallback),
         lldb.SBTypeSummary.CreateWithScriptCode(
             "return 'hello from callback summary'"))
     cat.AddTypeSynthetic(
         lldb.SBTypeNameSpecifier('formatters_with_callback.derives_from_base',
                                  lldb.eFormatterMatchCallback),
         lldb.SBTypeSynthetic.CreateWithClassName(
             'formatters_with_callback.SynthProvider'))
     cat.SetEnabled(True)