[Lldb-commits] [lldb] [LLDB] Add user documentation for DIL. (PR #228275)

[via lldb-commits]

================
@@ -0,0 +1,278 @@
+# DIL: The Data Inspection Language
+
+This page explains the Data Inspection Language (DIL) in LLDB. Most of this
+document is intended for LLDB users, from both the command line and through
+IDE's (Integrated Development Environments) via lldb-dap. At the end there is
+some additional information for LLDB developers.
+
+## Background: What is DIL and why did we implement it?
+
+As the name implies, the Data Inspection Language is a language that was created
+specifically to improve the stability and performance of program data
+introspection in LLDB, particularly when that introspection requires evaluating
+any simple expressions (which is often the case when data formatters and
+synthetic children are involved).
+
+Prior to the introduction of DIL, nearly all expression evaluations in LLDB had
+to be done through the full expression evaluator. This is a heavy-weight
+mechanism that uses Clang to fully parse C++ expressions, building up Clang ASTs
+to represent the expressions and then evaluating these Clang ASTs within the
+current LLDB context. This approach has historicaly had several drawbacks,
+including being somewhat slow and also sometimes crashing (mostly due to Clang
+being desing to expect complete, correct programs rather than partial contexts
+and expressions).
+
+DIL was designed to addresses these issues by avoiding Clang altogether. Instead
+it defines its own simple grammar, AST representation, lexer, parser and
+interpreter. By bypassing Clang, and only handling comparatively simple
+expressions, DIL can be both faster and more stable than the full expression
----------------
jimingham wrote:

I'll look at all this on Monday, thanks for going through all this again.

I don't like "re-presented" all that much either, but I'm not sure `formatted` is quite right either.  When you think of "formatting" a variable I think you would immediately assume we meant what `type format` does, just print something as hex or decimal, etc.  Then the argument makes no sense.  Why would the expression evaluator care whether somewhere else a variable printing was done in hex...

We've tied ourselves in the same knot generally where you have "Data Formatters" and then "format Data Formatters" as opposed to "Synthetic Child Data Formatters"...  We should have found a better word than format for that as well, but that's kind of water under the bridge at this point...

I think people would not expect from "formatting" is that it changes the child names of aggregate structures.  But it's understanding that that makes this all make sense.

But I don't have a better word, so maybe just make sure somewhere you say "by formatting I mean all the operations available in the Data Formatter system, including synthetic child providers" and a link to the formatters page...

https://github.com/llvm/llvm-project/pull/228275