[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Vassil Vassilev via Phabricator via cfe-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG3edd338a6407: [clang-repl] Add Documentation for Execution 
Results Handling. (authored by Krishna-13-cyber, committed by v.g.vassilev).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/conf.py

Index: clang/docs/conf.py
===
--- clang/docs/conf.py
+++ clang/docs/conf.py
@@ -49,6 +49,7 @@
 if sphinx.version_info >= (3, 0):
 # This requires 0.5 or later.
 extensions.append("recommonmark")
+extensions.append('sphinx.ext.graphviz')
 else:
 source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
 source_suffix[".md"] = "markdown"
Index: clang/docs/ClangRepl.rst
===
--- clang/docs/ClangRepl.rst
+++ clang/docs/ClangRepl.rst
@@ -213,6 +213,411 @@
 automatic language interoperability. It also helps static languages such as C/C++ become
 apt for data science.
 
+Execution Results Handling in Clang-Repl
+
+
+Execution Results Handling features discussed below help extend the Clang-Repl
+functionality by creating an interface between the execution results of a
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump
+for Value Printing/Automatic Printf, that is, to display the value and type of
+the captured data.
+
+
+1. Capture Execution Results
+
+
+In many cases, it is useful to bring back the program execution result to the
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-
+
+The synthesizer chooses which expression to synthesize, and then it replaces
+the original expression with the synthesized expression. Depending on the
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. graphviz::
+:name: valuesynthesis
+:caption: Value Synthesis
+:alt: Shows how an object of type 'Value' is synthesized
+:align: center
+
+ digraph "valuesynthesis" {
+ rankdir="LR";
+ graph [fontname="Verdana", fontsize="12"];
+ node [fontname="Verdana", fontsize="12"];
+ edge [fontname="Sans", fontsize="9"];
+
+ start [label=" Create an Object \n 'Last Value' \n of type 'Value' ", shape="note", fontcolor=white, fillcolor="#ff", style=filled];
+ assign [label=" Assign the result \n to the 'LastValue' \n (based on respective \n Memory Allocation \n scenario) ", shape="box"]
+ print [label=" Pretty Print \n the Value Object ", shape="Msquare", fillcolor="yellow", style=filled];
+ start -> assign;
+ assign -> print;
+
+   subgraph SynthesizeExpression {
+ synth [label=" SynthesizeExpr() ", shape="note", fontcolor=white, fillcolor="#ff", style=filled];
+ mem [label=" New Memory \n Allocation? ", shape="diamond"];
+ withaloc [label=" SetValueWithAlloc() ", shape="box"];
+ noaloc [label=" SetValueNoAlloc() ", shape="box"];
+ right [label=" 1. RValue Structure \n (a temporary value)", shape="box"];
+ left2 [label=" 2. LValue Structure \n (a variable with \n an address)", shape="box"];
+ left3 [label=" 3. Built-In Type \n (int, float, etc.)", shape="box"];
+ output [label=" move to 'Assign' step ", shape="box"];
+
+ synth -> mem;
+ mem -> withaloc [label="Yes"];
+ mem -> noaloc [label="No"];
+ withaloc -> right;
+ noaloc -> left2;
+ noaloc -> left3;
+ right -> output;
+ left2 -> output;
+ left3 -> output;
+  }
+output -> assign
+  }
+
+Where is the captured result stored?
+
+
+``LastValue`` holds the last result of the value printing. It is a class member
+because it can be accessed even after subsequent inputs.
+
+**Note:** If no value printing happens, then it is in an invalid state.
+
+Improving Efficiency and User Experience
+
+
+The Value object is essentially used to create a mapping between an expression
+'type' and the allocated 'memory'. Built-in types (bool, char, int,
+float, double, etc.) are copyable. Their their memory allocation size is 

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Vassil Vassilev via Phabricator via cfe-commits]

v.g.vassilev accepted this revision.
v.g.vassilev added a comment.

The pre-merge check seems to fail at clang-format for some reason. This patch 
does not change anything that should be formatted by clang-format.

We will try to add the images as editable graphviz content. We need to see if 
the infrastructure allows for this as suggested here: 
https://discourse.llvm.org/t/any-tool-for-creating-editable-diagrams-in-llvm-clang-repl-documentation-similar-to-mermaid-ingithub/72729/2


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher accepted this revision.
QuillPusher added a comment.
This revision is now accepted and ready to land.

Thanks @Krishna-13-cyber for the prompt efforts
@v.g.vassilev it is ready to commit as far as I can see


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber updated this revision to Diff 549745.
Krishna-13-cyber added a comment.

- Address the comments


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/conf.py

Index: clang/docs/conf.py
===
--- clang/docs/conf.py
+++ clang/docs/conf.py
@@ -49,6 +49,7 @@
 if sphinx.version_info >= (3, 0):
 # This requires 0.5 or later.
 extensions.append("recommonmark")
+extensions.append('sphinx.ext.graphviz')
 else:
 source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
 source_suffix[".md"] = "markdown"
Index: clang/docs/ClangRepl.rst
===
--- clang/docs/ClangRepl.rst
+++ clang/docs/ClangRepl.rst
@@ -213,6 +213,411 @@
 automatic language interoperability. It also helps static languages such as C/C++ become
 apt for data science.
 
+Execution Results Handling in Clang-Repl
+
+
+Execution Results Handling features discussed below help extend the Clang-Repl
+functionality by creating an interface between the execution results of a
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump
+for Value Printing/Automatic Printf, that is, to display the value and type of
+the captured data.
+
+
+1. Capture Execution Results
+
+
+In many cases, it is useful to bring back the program execution result to the
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-
+
+The synthesizer chooses which expression to synthesize, and then it replaces
+the original expression with the synthesized expression. Depending on the
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. graphviz::
+:name: valuesynthesis
+:caption: Value Synthesis
+:alt: Shows how an object of type 'Value' is synthesized
+:align: center
+
+ digraph "valuesynthesis" {
+ rankdir="LR";
+ graph [fontname="Verdana", fontsize="12"];
+ node [fontname="Verdana", fontsize="12"];
+ edge [fontname="Sans", fontsize="9"];
+
+ start [label=" Create an Object \n 'Last Value' \n of type 'Value' ", shape="note", fontcolor=white, fillcolor="#ff", style=filled];
+ assign [label=" Assign the result \n to the 'LastValue' \n (based on respective \n Memory Allocation \n scenario) ", shape="box"]
+ print [label=" Pretty Print \n the Value Object ", shape="Msquare", fillcolor="yellow", style=filled];
+ start -> assign;
+ assign -> print;
+
+   subgraph SynthesizeExpression {
+ synth [label=" SynthesizeExpr() ", shape="note", fontcolor=white, fillcolor="#ff", style=filled];
+ mem [label=" New Memory \n Allocation? ", shape="diamond"];
+ withaloc [label=" SetValueWithAlloc() ", shape="box"];
+ noaloc [label=" SetValueNoAlloc() ", shape="box"];
+ right [label=" 1. RValue Structure \n (a temporary value)", shape="box"];
+ left2 [label=" 2. LValue Structure \n (a variable with \n an address)", shape="box"];
+ left3 [label=" 3. Built-In Type \n (int, float, etc.)", shape="box"];
+ output [label=" move to 'Assign' step ", shape="box"];
+
+ synth -> mem;
+ mem -> withaloc [label="Yes"];
+ mem -> noaloc [label="No"];
+ withaloc -> right;
+ noaloc -> left2;
+ noaloc -> left3;
+ right -> output;
+ left2 -> output;
+ left3 -> output;
+  }
+output -> assign
+  }
+
+Where is the captured result stored?
+
+
+``LastValue`` holds the last result of the value printing. It is a class member
+because it can be accessed even after subsequent inputs.
+
+**Note:** If no value printing happens, then it is in an invalid state.
+
+Improving Efficiency and User Experience
+
+
+The Value object is essentially used to create a mapping between an expression
+'type' and the allocated 'memory'. Built-in types (bool, char, int,
+float, double, etc.) are copyable. Their their memory allocation size is known
+and the Value object can introduce a small-buffer optimization.
+In case of objects, the ``Value`` class provides reference-counted memory
+management.
+
+The 

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher added a comment.

@Krishna-13-cyber  added Graphviz code snippets to replace all .png images




Comment at: clang/docs/ClangRepl.rst:248-250
+.. image:: valuesynth.png
+   :align: center
+   :alt: valuesynth design

v.g.vassilev wrote:
> Can we replace that with its graphviz version?
.. graphviz::
:name: valuesynthesis
:caption: Value Synthesis
:alt: Shows how an object of type 'Value' is synthesized
:align: center

 digraph "valuesynthesis" {
 rankdir="LR";
 graph [fontname="Verdana", fontsize="12"];
 node [fontname="Verdana", fontsize="12"];
 edge [fontname="Sans", fontsize="9"];

 start [label=" Create an Object \n 'Last Value' \n of type 'Value' ", 
shape="note", fontcolor=white, fillcolor="#ff", style=filled];
 assign [label=" Assign the result \n to the 'LastValue' \n (based on 
respective \n Memory Allocation \n scenario) ", shape="box"]
 print [label=" Pretty Print \n the Value Object ", shape="Msquare", 
fillcolor="yellow", style=filled];
 start -> assign;
 assign -> print;

   subgraph SynthesizeExpression {
 synth [label=" SynthesizeExpr() ", shape="note", fontcolor=white, 
fillcolor="#ff", style=filled];
 mem [label=" New Memory \n Allocation? ", shape="diamond"];
 withaloc [label=" SetValueWithAlloc() ", shape="box"];
 noaloc [label=" SetValueNoAlloc() ", shape="box"];
 right [label=" 1. RValue Structure \n (a temporary value)", 
shape="box"];
 left2 [label=" 2. LValue Structure \n (a variable with \n an 
address)", shape="box"];
 left3 [label=" 3. Built-In Type \n (int, float, etc.)", 
shape="box"];
 output [label=" move to 'Assign' step ", shape="box"];

 synth -> mem;
 mem -> withaloc [label="Yes"];
 mem -> noaloc [label="No"];
 withaloc -> right;
 noaloc -> left2;
 noaloc -> left3;
 right -> output;
 left2 -> output;
 left3 -> output;
 }
 output -> assign;
}



Comment at: clang/docs/ClangRepl.rst:424-427
+
+.. image:: prettyprint.png
+   :align: center
+   :alt: prettyprint design

@Krishna-13-cyber please replace the image reference with the following code:


.. graphviz::
:name: parsing
:caption: Parsing Mechanism
:alt: Shows the Parsing Mechanism for Pretty Printing
:align: center

 digraph "prettyprint" {
 rankdir="LR";
 graph [fontname="Verdana", fontsize="12"];
 node [fontname="Verdana", fontsize="12"];
 edge [fontname="Verdana", fontsize="9"];

 parse [label=" ParseAndExecute() \n in Clang ", shape="box"];
 capture [label=" Capture 'Value' parameter \n for processing? ", 
shape="diamond"];
 use [label="  Use for processing  ", shape="box"];
 dump [label="  Validate and push  \n to dump()", shape="box"];
 callp [label="  call print() function ", shape="box"];
 type [label="  Print the Type \n ReplPrintTypeImpl()", shape="box"];
 data [label="  Print the Data \n ReplPrintDataImpl() ", shape="box"];
 output [label="  Output Pretty Print \n to the user  ", shape="box", 
fontcolor=white, fillcolor="#ff", style=filled];

 parse -> capture [label="Optional 'Value' Parameter"];
 capture -> use [label="Yes"];
 use -> End;
 capture -> dump [label="No"];
 dump -> callp;
 callp -> type;
 callp -> data;
 type -> output;
 data -> output;
}


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Vassil Vassilev via Phabricator via cfe-commits]

v.g.vassilev added inline comments.



Comment at: clang/docs/ClangRepl.rst:221
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 

We should probably spell consistently `Clang-Repl`.



Comment at: clang/docs/ClangRepl.rst:248
+
+.. image:: valuesynth.png
+   :align: center

Can we replace that with its graphviz version?



Comment at: clang/docs/ClangRepl.rst:264
+The Value object is essentially used to create a mapping between an expression 
+'type' and the 'memory' to be allocated. Built-in types (bool, char, int, 
+float, double, etc.) are simpler, since their memory allocation size is known. 





Comment at: clang/docs/ClangRepl.rst:265
+'type' and the 'memory' to be allocated. Built-in types (bool, char, int, 
+float, double, etc.) are simpler, since their memory allocation size is known. 
+In case of objects, a pointer can be saved, since the size of the object is 





Comment at: clang/docs/ClangRepl.rst:266-267
+float, double, etc.) are simpler, since their memory allocation size is known. 
+In case of objects, a pointer can be saved, since the size of the object is 
+not known.
+





Comment at: clang/docs/ClangRepl.rst:269-274
+For further improvement, the underlying Clang Type is also identified. For 
+example, ``X(char, Char_S)``, where ``Char_S`` is the Clang type. Clang types 
are 
+very efficient, which is important since these will be used in hotspots (high 
+utilization areas of the program). The ``Value.h`` header file has a very low 
+token count and was developed with strict constraints in mind, since it can 
+affect the performance of the interpreter.





Comment at: clang/docs/ClangRepl.rst:276-278
+This also enables the user to receive the computed 'type' back in their code 
+and then transform the type into something else (e.g., transform a double into 
+a float). Normally, the compiler can handle these conversions transparently, 





Comment at: clang/docs/ClangRepl.rst:284
+On-request conversions can help improve the user experience, by allowing 
+conversion to a desired 'to' type, when the 'from' type is unknown or unclear
+





Comment at: clang/docs/ClangRepl.rst:296-298
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 
+and Python.

QuillPusher wrote:
> @Krishna-13-cyber 
> 
> Please change CPPYY to cppyy
> 
> I just saw they use small caps on their official website




Comment at: clang/docs/ClangRepl.rst:352
+
+In Clang-REPL there is **interpreted code**, and this feature adds a 'value' 
+runtime that can talk to the **compiled code**.





Comment at: clang/docs/ClangRepl.rst:404
+this feature added to upstream Clang repo has essentially extended the syntax 
of
+C++,so that it can be more helpful for people that are writing code for data 
+science applications.





Comment at: clang/docs/ClangRepl.rst:419
+
+The Interpreter in Clang-REPL (``interpreter.cpp``) includes the function 
+``ParseAndExecute()`` that can accept a 'Value' parameter to capture the 
result. 





Comment at: clang/docs/ClangRepl.rst:461
+
+This feature uses a new token (annot_repl_input_end) to consider printing the 
+value of an expression if it doesn't end with a semicolon. When parsing an 




Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher added inline comments.



Comment at: clang/docs/ClangRepl.rst:393-396
+
+.. image:: autoprint.png
+   :align: center
+   :alt: autoprint design

Please replace the image reference with the following Graphviz code (do not 
delete the image .png for now, we need to commit and see if graphviz works out 
of the box).

.. graphviz::
:name: automaticprintf
:caption: Automatic PrintF
:alt: Shows how Automatic PrintF can be used
:align: center

 digraph "AutomaticPrintF" {
 size="6,4";
 rankdir="LR";
 graph [fontname="Verdana", fontsize="12"];
 node [fontname="Verdana", fontsize="12"];
 edge [fontname="Sans", fontsize="9"];

 manual [label=" Manual PrintF ", shape="box"];
 int1 [label=" int ( &) 42 ", shape="box"]
 auto [label=" Automatic PrintF ", shape="box"];
 int2 [label=" int ( &) 42 ", shape="box"]

 auto -> int2 [label="int x = 42; \n x"];
 manual -> int1 [label="int x = 42; \n printf((int &) %d 
\\n, x);"];
 }



Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher requested changes to this revision.
QuillPusher added a comment.
This revision now requires changes to proceed.

Added minor changes requested by Vassil




Comment at: clang/docs/ClangRepl.rst:296
+
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 

@Krishna-13-cyber 

Please change CPPYY to cppyy

I just saw they use small caps on their official website



Comment at: clang/docs/ClangRepl.rst:298
+C++ within Python. It enables transporting values/information between C++ 
+and Python.
+

@Krishna-13-cyber 

Please add the following note under this paragraph, as requested by Vassil in 
previous comment:

**Note:** `cppyy`_ is an automatic, run-time, Python-to-C++ bindings 
generator, for calling C++ from Python and Python from C++. It uses LLVM along 
with a C++ interpreter (e.g., Cling) to enable features like run-time 
instantiation of C++ templates, cross-inheritance, callbacks, auto-casting, 
transparent use of smart pointers, etc.

.. _cppyy: https://github.com/wlav/cppyy/


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher accepted this revision.
QuillPusher added a comment.
This revision is now accepted and ready to land.

accepting current revision, one minor change is still required, adding that 
separately


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber updated this revision to Diff 549034.
Krishna-13-cyber added a comment.

- Address the comments


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/autoprint.png
  clang/docs/prettyprint.png
  clang/docs/valuesynth.png

Index: clang/docs/ClangRepl.rst
===
--- clang/docs/ClangRepl.rst
+++ clang/docs/ClangRepl.rst
@@ -215,6 +215,319 @@
 automatic language interoperability. It also helps static languages such as C/C++ become
 apt for data science.
 
+Execution Results Handling in Clang-Repl
+
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results 
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump 
+for Value Printing/Automatic Printf, that is, to display the value and type of 
+the captured data. 
+
+
+1. Capture Execution Results
+
+
+In many cases, it is useful to bring back the program execution result to the 
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-
+
+The synthesizer chooses which expression to synthesize, and then it replaces 
+the original expression with the synthesized expression. Depending on the 
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. image:: valuesynth.png
+   :align: center
+   :alt: valuesynth design
+
+Where is the captured result stored?
+
+
+``LastValue`` holds the last result of the value printing. It is a class member 
+because it can be accessed even after subsequent inputs. 
+
+**Note:** If no value printing happens, then it is in an invalid state. 
+
+Improving Efficiency and User Experience
+
+
+The Value object is essentially used to create a mapping between an expression 
+'type' and the 'memory' to be allocated. Built-in types (bool, char, int, 
+float, double, etc.) are simpler, since their memory allocation size is known. 
+In case of objects, a pointer can be saved, since the size of the object is 
+not known.
+
+For further improvement, the underlying Clang Type is also identified. For 
+example, ``X(char, Char_S)``, where ``Char_S`` is the Clang type. Clang types are 
+very efficient, which is important since these will be used in hotspots (high 
+utilization areas of the program). The ``Value.h`` header file has a very low 
+token count and was developed with strict constraints in mind, since it can 
+affect the performance of the interpreter.
+
+This also enables the user to receive the computed 'type' back in their code 
+and then transform the type into something else (e.g., transform a double into 
+a float). Normally, the compiler can handle these conversions transparently, 
+but in interpreter mode, the compiler cannot see all the 'from' and 'to' types,
+so it cannot implicitly do the conversions. So this logic enables providing 
+these conversions on request. 
+
+On-request conversions can help improve the user experience, by allowing 
+conversion to a desired 'to' type, when the 'from' type is unknown or unclear
+
+Significance of this Feature
+
+
+The 'Value' object enables wrapping a memory region that comes from the 
+JIT, and bringing it back to the compiled code (and vice versa). 
+This is a very useful functionality when:
+
+- connecting an interpreter to the compiled code, or
+- connecting an interpreter in another language.
+
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 
+and Python.
+
+In a nutshell, this feature enables a new way of developing code, paving the 
+way for language interoperability and easier interactive programming.
+
+Implementation Details
+==
+
+Interpreter as a REPL vs. as a Library
+--
+
+1 - If we're using the interpreter in interactive (REPL) mode, it will dump 
+the value (i.e., value printing).
+
+.. code-block:: console
+
+  if (LastValue.isValid()) {
+if (!V) {
+  LastValue.dump();
+  LastValue.clear();
+} else
+  *V = std::move(LastValue);
+  }
+
+
+2 - If we're using the interpreter as a library, then it will pass the value 
+to the user.
+
+Incremental AST Consumer

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher requested changes to this revision.
QuillPusher added a comment.
This revision now requires changes to proceed.

added minor changes based on Vassil's review during docs meeting




Comment at: clang/docs/ClangRepl.rst:220-230
+
+:doc:`ExecutionResultsHandling` helps extend the Clang-REPL functionality by
+creating an interface between the execution results of a program and the 
compiled
+program. Following are its main components:
+
+- Capture Execution Results: This feature helps capture the execution results
+  of a program and bring them back to the compiled program.

As per Vassil's comment below, please move all the Execution Results handling 
text in the main Clang-Repl doc instead of a separate ExecutionResultsHandling 
document

So this paragraph can be removed and all the content from the 
ExecutionResultsHandling.rst can be included here in this ClangRepl.rst document



Comment at: clang/docs/ExecutionResultsHandling.rst:119-127
+
+.. code-block:: console
+
+for (Decl *D : DGR)
+  if (auto *TSD = llvm::dyn_cast(D);
+  TSD && TSD->isSemiMissing())
+TSD->setStmt(Interp.SynthesizeExpr(cast(TSD->getStmt(;

Add note before code snippet

**Note:** Following is a sample code snippet. Actual code may vary over time.



Comment at: clang/docs/ExecutionResultsHandling.rst:237-256
+.. code-block:: console
+
+void Value::print(llvm::raw_ostream ) const {
+assert(OpaqueType != nullptr && "Can't print default Value");
+
+if (getType()->isVoidType() || !isValid())
+return;

please remove this code block, it is not needed



Comment at: clang/docs/index.rst:96
ClangRepl
+   ExecutionResultsHandling
 

v.g.vassilev wrote:
> We should probably move that under `ClangRepl`.
> We should probably move that under `ClangRepl`.

@Krishna-13-cyber I have commented above, where the excerpt paragraph in 
CalngRepl.rst can be removed and all content from ExecutionResultsHandling.rst 
can be included (and remove file ExecutionResultsHandling.rst after that)


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Vassil Vassilev via Phabricator via cfe-commits]

v.g.vassilev added inline comments.



Comment at: clang/docs/ExecutionResultsHandling.rst:80
+
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 

cppyy seems undefined here.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher accepted this revision.
QuillPusher added a comment.
This revision is now accepted and ready to land.

Thanks @Krishna-13-cyber for the prompt changes.

@v.g.vassilev If no further changes are required by @junaire , then this should 
be ready to merge


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber updated this revision to Diff 547574.
Krishna-13-cyber added a comment.

- Update section of Execution Results Handling in Clang-REPL


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/ExecutionResultsHandling.rst
  clang/docs/autoprint.png
  clang/docs/index.rst
  clang/docs/prettyprint.png
  clang/docs/valuesynth.png

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -93,6 +93,7 @@
ClangOffloadBundler
ClangOffloadPackager
ClangRepl
+   ExecutionResultsHandling
 
 Design Documents
 
Index: clang/docs/ExecutionResultsHandling.rst
===
--- /dev/null
+++ clang/docs/ExecutionResultsHandling.rst
@@ -0,0 +1,333 @@
+=
+Execution Results Handling in Clang-REPL
+=
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results 
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump 
+for Value Printing/Automatic Printf, that is, to display the value and type of 
+the captured data. 
+
+
+1. Capture Execution Results
+
+
+In many cases, it is useful to bring back the program execution result to the 
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-
+
+The synthesizer chooses which expression to synthesize, and then it replaces 
+the original expression with the synthesized expression. Depending on the 
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. image:: valuesynth.png
+   :align: center
+   :alt: valuesynth design
+
+Where is the captured result stored?
+
+
+``LastValue`` holds the last result of the value printing. It is a class member 
+because it can be accessed even after subsequent inputs. 
+
+**Note:** If no value printing happens, then it is in an invalid state. 
+
+Improving Efficiency and User Experience
+
+
+The Value object is essentially used to create a mapping between an expression 
+'type' and the 'memory' to be allocated. Built-in types (bool, char, int, 
+float, double, etc.) are simpler, since their memory allocation size is known. 
+In case of objects, a pointer can be saved, since the size of the object is 
+not known.
+
+For further improvement, the underlying Clang Type is also identified. For 
+example, ``X(char, Char_S)``, where ``Char_S`` is the Clang type. Clang types are 
+very efficient, which is important since these will be used in hotspots (high 
+utilization areas of the program). The ``Value.h`` header file has a very low 
+token count and was developed with strict constraints in mind, since it can 
+affect the performance of the interpreter.
+
+This also enables the user to receive the computed 'type' back in their code 
+and then transform the type into something else (e.g., transform a double into 
+a float). Normally, the compiler can handle these conversions transparently, 
+but in interpreter mode, the compiler cannot see all the 'from' and 'to' types,
+so it cannot implicitly do the conversions. So this logic enables providing 
+these conversions on request. 
+
+On-request conversions can help improve the user experience, by allowing 
+conversion to a desired 'to' type, when the 'from' type is unknown or unclear
+
+Significance of this Feature
+
+
+The 'Value' object enables wrapping a memory region that comes from the 
+JIT, and bringing it back to the compiled code (and vice versa). 
+This is a very useful functionality when:
+
+- connecting an interpreter to the compiled code, or
+- connecting an interpreter in another language.
+
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 
+and Python.
+
+In a nutshell, this feature enables a new way of developing code, paving the 
+way for language interoperability and easier interactive programming.
+
+Implementation Details
+==
+
+Interpreter as a REPL vs. as a Library
+--
+
+1 - If we're using the interpreter in interactive (REPL) mode, it will dump 
+the 

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber updated this revision to Diff 547529.
Krishna-13-cyber added a comment.

- Address the comments


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/ExecutionResultsHandling.rst
  clang/docs/autoprint.png
  clang/docs/index.rst
  clang/docs/prettyprint.png
  clang/docs/valuesynth.png

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -93,6 +93,7 @@
ClangOffloadBundler
ClangOffloadPackager
ClangRepl
+   ExecutionResultsHandling
 
 Design Documents
 
Index: clang/docs/ExecutionResultsHandling.rst
===
--- /dev/null
+++ clang/docs/ExecutionResultsHandling.rst
@@ -0,0 +1,333 @@
+=
+Execution Results Handling in Clang-REPL
+=
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results 
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump 
+for Value Printing/Automatic Printf, that is, to display the value and type of 
+the captured data. 
+
+
+1. Capture Execution Results
+
+
+In many cases, it is useful to bring back the program execution result to the 
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-
+
+The synthesizer chooses which expression to synthesize, and then it replaces 
+the original expression with the synthesized expression. Depending on the 
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. image:: valuesynth.png
+   :align: center
+   :alt: valuesynth design
+
+Where is the captured result stored?
+
+
+``LastValue`` holds the last result of the value printing. It is a class member 
+because it can be accessed even after subsequent inputs. 
+
+**Note:** If no value printing happens, then it is in an invalid state. 
+
+Improving Efficiency and User Experience
+
+
+The Value object is essentially used to create a mapping between an expression 
+'type' and the 'memory' to be allocated. Built-in types (bool, char, int, 
+float, double, etc.) are simpler, since their memory allocation size is known. 
+In case of objects, a pointer can be saved, since the size of the object is 
+not known.
+
+For further improvement, the underlying Clang Type is also identified. For 
+example, ``X(char, Char_S)``, where ``Char_S`` is the Clang type. Clang types are 
+very efficient, which is important since these will be used in hotspots (high 
+utilization areas of the program). The ``Value.h`` header file has a very low 
+token count and was developed with strict constraints in mind, since it can 
+affect the performance of the interpreter.
+
+This also enables the user to receive the computed 'type' back in their code 
+and then transform the type into something else (e.g., transform a double into 
+a float). Normally, the compiler can handle these conversions transparently, 
+but in interpreter mode, the compiler cannot see all the 'from' and 'to' types,
+so it cannot implicitly do the conversions. So this logic enables providing 
+these conversions on request. 
+
+On-request conversions can help improve the user experience, by allowing 
+conversion to a desired 'to' type, when the 'from' type is unknown or unclear
+
+Significance of this Feature
+
+
+The 'Value' object enables wrapping a memory region that comes from the 
+JIT, and bringing it back to the compiled code (and vice versa). 
+This is a very useful functionality when:
+
+- connecting an interpreter to the compiled code, or
+- connecting an interpreter in another language.
+
+For example, the CPPYY code makes use of this feature to enable running 
+C++ within Python. It enables transporting values/information between C++ 
+and Python.
+
+In a nutshell, this feature enables a new way of developing code, paving the 
+way for language interoperability and easier interactive programming.
+
+Implementation Details
+==
+
+Interpreter as a REPL vs. as a Library
+--
+
+1 - If we're using the interpreter in interactive (REPL) mode, it will dump 
+the value (i.e., value printing).
+
+.. 

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher requested changes to this revision.
QuillPusher added a comment.
This revision now requires changes to proceed.

Thanks @junaire for the clarification, following is the updated document 
structure:

1. Capture Execution Results
  - How the Feature works
  - more details
  - Implementation Details

2. Dump Captured Execution Results¶
  - How- the Feature works
  - more details
  - Implementation Details

@Krishna-13-cyber Please use the attached file named 
ExecutionResultsHandling.rst as the latest doc, so Jun can review the updated 
document.

F28589747: ExecutionResultsHandling.rst 




Comment at: clang/docs/ClangRepl.rst:217-232
 
+Execution Results Handling in Clang-Repl
+
+
+:doc:`ExecutionResultsHandling` features discussed below help extend the 
Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.

Execution Results Handling in Clang-Repl
===

:doc:`ExecutionResultsHandling` helps extend the Clang-REPL functionality by 
creating an interface between the execution results of a program and the 
compiled 
program. Following are its main components:

1 - **Capture Execution Results**: This feature helps capture the execution 
results 
of a program and bring them back to the compiled program.

2 - **Dump Captured Execution Results**: This feature helps create a temporary 
dump 
for Value Printing/Automatic Printf, that is, to display the value and type of 
the captured data.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Jun Zhang via Phabricator via cfe-commits]

junaire added a comment.

I want to clarify: We offer two features: 1. capture the execution results and 
bring it back to the compiled program. 2. dump the captured value (value 
printing/automatic printf) and all the parsing, ast transform and balabala, 
these are all implementation details. The doc looks fine but may need a bit of 
restructuring. I'd suggest you split them into:

1. what do we offer? what are the new features? why are they important? The two 
I mentioned above
2. how these are implemented? what does the underhood look like? annotation 
token, code synthesis, etc...
3. further information, RFC and etc...


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher accepted this revision.
QuillPusher added a comment.
This revision is now accepted and ready to land.

Thanks for the updates, look OK to me


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber updated this revision to Diff 547231.
Krishna-13-cyber added a comment.

- Addressed the comments


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

Files:
  clang/docs/ClangRepl.rst
  clang/docs/ExecutionResultsHandling.rst
  clang/docs/autoprint.png
  clang/docs/index.rst
  clang/docs/prettyprint.png
  clang/docs/valuesynth.png

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -93,6 +93,7 @@
ClangOffloadBundler
ClangOffloadPackager
ClangRepl
+   ExecutionResultsHandling
 
 Design Documents
 
Index: clang/docs/ExecutionResultsHandling.rst
===
--- /dev/null
+++ clang/docs/ExecutionResultsHandling.rst
@@ -0,0 +1,341 @@
+=
+Execution Results Handling in Clang-REPL
+=
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.
+
+- The Automatic Printf feature makes it easy to display variable values 
+  during program execution.
+
+- The Value Synthesis feature helps store the execution results 
+  (to be able to bring them back to the compiled program).
+
+- The Pretty Printing feature helps create a temporary dump to display the value
+  and type (pretty print) of the desired data. 
+
+1. Automatic Printf
+===
+
+The `Automatic Printf` feature makes it easy to display variable values during 
+program execution. Using the `printf` function repeatedly is not required. 
+This is achieved using an extension in the `libclangInterpreter` library.
+
+To automatically print the value of an expression, simply write the expression 
+in the global scope **without a semicolon**.
+
+.. image:: autoprint.png
+   :align: center
+   :alt: autoprint design
+
+Examples
+
+.. code-block:: console
+
+clang-repl> int x = 42;
+clang-repl> x   // equivalent to calling printf("(int &) %d\n", x);
+(int &) 42
+
+clang-repl> std::vector v = {1,2,3};
+clang-repl> v  // This syntax is fine after D127284 
+(std::vector &) {1,2,3}
+
+clang-repl> "Hello, interactive C++!"
+(const char [24]) "Hello, interactive C++!"
+
+Significance of this feature
+
+
+Inspired by a similar implementation in `Cling `_,
+this feature added to upstream Clang repo has essentially extended the syntax of
+C++,so that it can be more helpful for people that are writing code for data 
+science applications.
+ 
+This is useful, for example, when you want to experiment with a set of values 
+against a set of functions, and you'd like to know the results right away. 
+This is similar to how Python works (hence its popularity in data science 
+research), but the superior performance of C++, along with this flexibility 
+makes it a more attractive option.
+
+Annotation Token (annot_repl_input_end)
+---
+
+This feature uses a new token (annot_repl_input_end) to consider printing the 
+value of an expression if it doesn't end with a semicolon. When parsing an 
+Expression Statement, if the last semicolon is missing, then the code will 
+pretend that there one and set a marker there for later utilization, and 
+continue parsing.
+
+A semicolon is normally required in C++, but this feature expands the C++ 
+syntax to handle cases where a missing semicolon is expected (i.e., when 
+handling an expression statement). It also makes sure that an error is not 
+generated for the missing semicolon in this specific case. 
+
+This is accomplished by identifying the end position of the user input 
+(expression statement). This helps store and return the expression statement 
+effectively, so that it can be printed (displayed to the user automatically).
+
+**Note:** This logic is only available for C++ for now, since part of the 
+implementation itself requires C++ features. Future versions may support more 
+languages.
+
+.. code-block:: console
+
+  Token *CurTok = nullptr;
+  // If the semicolon is missing at the end of REPL input, consider if
+  // we want to do value printing. Note this is only enabled in C++ mode
+  // since part of the implementation requires C++ language features.
+  // Note we shouldn't eat the token since the callback needs it.
+  if (Tok.is(tok::annot_repl_input_end) && Actions.getLangOpts().CPlusPlus)
+CurTok = 
+  else
+// Otherwise, eat the semicolon.
+ExpectAndConsumeSemi(diag::err_expected_semi_after_expr);
+
+  StmtResult R = handleExprStmt(Expr, StmtCtx);
+  if (CurTok && !R.isInvalid())
+CurTok->setAnnotationValue(R.get());
+
+  return R;
+}
+
+AST 

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Vassil Vassilev via Phabricator via cfe-commits]

v.g.vassilev added inline comments.



Comment at: clang/docs/index.rst:96
ClangRepl
+   ExecutionResultsHandling
 

We should probably move that under `ClangRepl`.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[QuillPusher via Phabricator via cfe-commits]

QuillPusher requested changes to this revision.
QuillPusher added a comment.
This revision now requires changes to proceed.

added some comments for minor changes. Two sections to be removed since they 
are not yet merged to upstream code:

- Complex Data Types
- Users can create their own types




Comment at: clang/docs/ExecutionResultsHandling.rst:50-52
+Inspired by a similar implementation in `Cling 
`_,
+this feature added to upstream Clang repo has essentially extended the syntax 
of C++,
+so that it can be more helpful for people that are writing code for data 
science applications.

@Krishna-13-cyber  This paragraph is exceeding 80 columns. Please reformat to 
limit to 80 columns



Comment at: clang/docs/ExecutionResultsHandling.rst:55
+This is useful, for example, when you want to experiment with a set of values 
+against a set of functions, and you'd like to know the results right-away. 
+This is similar to how Python works (hence its popularity in data science 

Please remove the hyphen: 

right-away -> right away

(must have carried through from previous tool's preview)



Comment at: clang/docs/ExecutionResultsHandling.rst:257-259
+`Above is an example of interoperability between the compiled code and the 
+interpreted code. Interoperability between languages (e.g., C++ and Python) 
+works similarly.`

Formatting for this note seems different, it is enclosed in single quotes. Did 
you mean **Note:** or  " " ?



Comment at: clang/docs/ExecutionResultsHandling.rst:268
+
+How it works?
+---

Please remove the question mark, this is an expression, not a question (common 
mistake)

How it works? -> How it works

Note that another heading has a question mark (**Where is the captured result 
stored?**). That question mark is OK, since that is actually mimicking a user's 
question. So leave that one as it is.



Comment at: clang/docs/ExecutionResultsHandling.rst:283
+
+.. code-block:: console
+

@Krishna-13-cyber please add a note/comment above the code block:

Note: Following is a sample code snippet. Actual code may vary over time.



Comment at: clang/docs/ExecutionResultsHandling.rst:329-356
+
+Complex Data Types:
+---
+
+This feature can print out primitive types (int, char, bool, etc.) easily. 
+For more complex types (e.g., `std::vector`), it falls back to a runtime 
+function call using the following helper function.

@Krishna-13-cyber please remove the "Complex Data Types" section, since this is 
not merged into the upstream LLVM code yet.
@junaire can confirm.



Comment at: clang/docs/ExecutionResultsHandling.rst:357-371
+
+Users can create their own types:
+-
+
+All overloads live in a header, which are included at runtime. So **print a 
+std::vector** is equivalent to `PrintValueRuntime();`.
+

@Krishna-13-cyber please remove the "Users can create their own types" section, 
since this is not merged into the upstream LLVM code yet.
@junaire can confirm.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D156858/new/

https://reviews.llvm.org/D156858

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D156858: Add Documentation for Execution Results Handling in Clang-REPL

[Krishna Narayanan via Phabricator via cfe-commits]

Krishna-13-cyber created this revision.
Krishna-13-cyber added reviewers: v.g.vassilev, davidlange6, QuillPusher.
Herald added a subscriber: arphaman.
Herald added a project: All.
Krishna-13-cyber requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.

This patch adds documentation for execution results handling in Clang-REPL with 
the below features:

- Automatic Printf feature
- Value Synthesis feature
- Pretty Printing feature


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D156858

Files:
  clang/docs/ExecutionResultsHandling.rst
  clang/docs/autoprint.png
  clang/docs/index.rst
  clang/docs/prettyprint.png
  clang/docs/valuesynth.png

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -93,6 +93,7 @@
ClangOffloadBundler
ClangOffloadPackager
ClangRepl
+   ExecutionResultsHandling
 
 Design Documents
 
Index: clang/docs/ExecutionResultsHandling.rst
===
--- /dev/null
+++ clang/docs/ExecutionResultsHandling.rst
@@ -0,0 +1,381 @@
+=
+Execution Results Handling in Clang-REPL
+=
+
+Execution Results Handling features discussed below help extend the Clang-REPL 
+functionality by creating an interface between the execution results of a 
+program and the compiled program.
+
+- The Automatic Printf feature makes it easy to display variable values 
+  during program execution.
+
+- The Value Synthesis feature helps store the execution results 
+  (to be able to bring them back to the compiled program).
+
+- The Pretty Printing feature helps create a temporary dump to display the value
+  and type (pretty print) of the desired data. 
+
+1. Automatic Printf
+===
+
+The `Automatic Printf` feature makes it easy to display variable values during 
+program execution. Using the `printf` function repeatedly is not required. 
+This is achieved using an extension in the `libclangInterpreter` library.
+
+To automatically print the value of an expression, simply write the expression 
+in the global scope **without a semicolon**.
+
+.. image:: autoprint.png
+   :align: center
+   :alt: autoprint design
+
+Examples
+
+.. code-block:: console
+
+clang-repl> int x = 42;
+clang-repl> x   // equivalent to calling printf("(int &) %d\n", x);
+(int &) 42
+
+clang-repl> std::vector v = {1,2,3};
+clang-repl> v  // This syntax is fine after D127284 
+(std::vector &) {1,2,3}
+
+clang-repl> "Hello, interactive C++!"
+(const char [24]) "Hello, interactive C++!"
+
+Significance of this feature
+
+
+Inspired by a similar implementation in `Cling `_,
+this feature added to upstream Clang repo has essentially extended the syntax of C++,
+so that it can be more helpful for people that are writing code for data science applications.
+ 
+This is useful, for example, when you want to experiment with a set of values 
+against a set of functions, and you'd like to know the results right-away. 
+This is similar to how Python works (hence its popularity in data science 
+research), but the superior performance of C++, along with this flexibility 
+makes it a more attractive option.
+
+Annotation Token (annot_repl_input_end)
+---
+
+This feature uses a new token (annot_repl_input_end) to consider printing the 
+value of an expression if it doesn't end with a semicolon. When parsing an 
+Expression Statement, if the last semicolon is missing, then the code will 
+pretend that there one and set a marker there for later utilization, and 
+continue parsing.
+
+A semicolon is normally required in C++, but this feature expands the C++ 
+syntax to handle cases where a missing semicolon is expected (i.e., when 
+handling an expression statement). It also makes sure that an error is not 
+generated for the missing semicolon in this specific case. 
+
+This is accomplished by identifying the end position of the user input 
+(expression statement). This helps store and return the expression statement 
+effectively, so that it can be printed (displayed to the user automatically).
+
+**Note:** This logic is only available for C++ for now, since part of the 
+implementation itself requires C++ features. Future versions may support more 
+languages.
+
+.. code-block:: console
+
+  Token *CurTok = nullptr;
+  // If the semicolon is missing at the end of REPL input, consider if
+  // we want to do value printing. Note this is only enabled in C++ mode
+  // since part of the implementation requires C++ language features.
+  // Note we shouldn't eat the token since the callback needs it.
+  if (Tok.is(tok::annot_repl_input_end) && Actions.getLangOpts().CPlusPlus)
+CurTok = 
+