Add opencombine_lldb.py for better Demand formatting in lldb/Xcode (#146)

README.md

@@ -89,3 +89,16 @@ GYB template files have the `.gyb` extension. Run `make gyb` to generate Swift c
 templates. The generated files are prefixed with `GENERATED-`  and are checked into source control. Those
 files should never be edited directly. Instead, the `.gyb` template should be edited, and after that the files
 should be regenerated using `make gyb`.
+
+#### Debugger Support
+
+The file `opencombine_lldb.py`  defines some `lldb` type summaries for easier debugging. These type summaries improve the way `lldb` and Xcode display some OpenCombine values.
+
+To use `opencombine_lldb.py`, figure out its full path. Let's say the full path is `~/projects/OpenCombine/opencombine_lldb.py`. Then the following statement to your `~/.lldbinit` file:
+
+    command script import ~/projects/OpenCombine/opencombine_lldb.py
+
+Currently, `opencombine_lldb.py` defines type summaries for these types:
+
+- `Subscribers.Demand`
+- That's all for now.

opencombine_lldb.py

@@ -0,0 +1,29 @@
+# To use `opencombine_lldb.py`, figure out its full path.
+# Let's say the full path is `~/projects/OpenCombine/opencombine_lldb.py`.
+# Then add the following statement to your `~/.lldbinit` file:
+#
+#     command script import ~/projects/OpenCombine/opencombine_lldb.py
+
+import lldb
+
+# Show a Demand as either `max(N)` or `unlimited`.
+def summary_Demand(sb_value, internal_dict):
+    child = sb_value.GetChildAtIndex(0)
+    if not child.IsValid():
+        return 'failed to get child of Demand'
+    number = child.GetValueAsUnsigned()
+
+    # .unlimited is represented by a rawValue of UInt(Int.max) + 1.
+    # Int.max is either 2**31 - 1 or 2**63 - 1 depending on the
+    # target platform. So .unlimited is either 2**31 or 2**63.
+    #     31 = 4 * 8 - 1
+    #     63 = 8 * 8 - 1
+    unlimited = 2**(child.GetByteSize() * 8 - 1)
+
+    if number == unlimited:
+        return 'unlimited'
+    else:
+        return 'max(%d)' % number
+
+def __lldb_init_module(debugger, internal_dict):
+    debugger.HandleCommand('type summary add -w swift OpenCombine.Subscribers.Demand -F "' + __name__ + '.summary_Demand"')