<commit_before>================================================
=
=   Tutorial about Dominators and Control Flow
=   revised version of Dominator.txt by koenigr
= 
================================================



1) Definition of Dominator and Postdominator
================================================

A statement d dominates a statement t if every path going to t has to go trough d.                             
A statement p postdominates a statement t if every path starting at t has to go through p.

See https://en.wikipedia.org/wiki/Dominator_(graph_theory) 


Examples:



                 (stmt) -------->(stmt)
                  /                 \
                 /                   \
                /                     \
---------> (ifStmt t) ------------> (stmt p)------> (stmt)
          			           p is postdominator of t
          


                 (stmt) -------->(stmt)
                  /                 \
                 /                   \
                /                     \
---------> (ifStmt d) ------------> (stmt t)------> (stmt)
            d is dominator of t



2) Dominators in the Source-Code: List of possibly interesting files
====================================================================

- MHGDominatorsFinder<N> (DirectedGraph<N> graph)
- MHGPostDominatorsFinder(DirectedGraph<N< graph)
- MHGPostDominatorsFinder.getDominators
- MHGPostDominatorsFinder.getImmediateDominator
- postdominatorfinder.getDominators(stmt).contains(s)
- UnitGraph graph = new BriefUnitGraph(body)
- soot.toolkits.graph.UnitGraph+
- soot.toolkits.graph.BriefUnitGraph.
- BriefUnitGraph(Body body)



3) Control flow in Java vs Jimple
======================================================

Consider the following java code, where b0, b1, ... etc are boolean
expressions like x < 3 or y > 0 and stm0, stm1, ... are statements like
x = 4, y = x + 7.

if (b0) {
	stm0
} else if (b1) {
	stm1
} else {
	stm2
}

This is translated to the following Jimple Code:

	if !b0 goto label0
	stm0
	goto label2
  
  label 0:
    if !b1 goto label1
    stm1
    goto label2
  
  label1:
    stm2
  
  label2:
    ... 




























<commit_msg>add reworked dominator docu<commit_after>================================================
=
=   Tutorial about Dominators and Control Flow
=   revised version of Dominator.txt by koenigr
= 
================================================



1) Definition of Dominator and Postdominator
================================================

A statement d dominates a statement t if every path going to t has to go trough d.                             
A statement p postdominates a statement t if every path starting at t has to go through p.

See https://en.wikipedia.org/wiki/Dominator_(graph_theory) 


Examples:



                 (stmt) -------->(stmt)
                  /                 \
                 /                   \
                /                     \
---------> (ifStmt t) ------------> (stmt p)------> (stmt)
          			           p is postdominator of t
          


                 (stmt) -------->(stmt)
                  /                 \
                 /                   \
                /                     \
---------> (ifStmt d) ------------> (stmt t)------> (stmt)
            d is dominator of t



2) Dominators in the Source-Code: List of possibly interesting files
====================================================================

- MHGDominatorsFinder<N> (DirectedGraph<N> graph)
- MHGPostDominatorsFinder(DirectedGraph<N< graph)
- MHGPostDominatorsFinder.getDominators
- MHGPostDominatorsFinder.getImmediateDominator
- postdominatorfinder.getDominators(stmt).contains(s)
- UnitGraph graph = new BriefUnitGraph(body)
- soot.toolkits.graph.UnitGraph+
- soot.toolkits.graph.BriefUnitGraph.
- BriefUnitGraph(Body body)



3) Control flow in Java vs Jimple
======================================================

Consider the following java code, where b0, b1, ... etc are boolean
expressions like x < 3 or y > 0 and stm0, stm1, ... are statements like
x = 4, y = x + 7.

if (b0) {
	stm0
} else if (b1) {
	stm1
} else {
	stm2
}

This is translated to the following Jimple Code:

	if !b0 goto label0
	stm0
	goto label2
  
  label 0:
    if !b1 goto label1
    stm1
    goto label2
  
  label1:
    stm2
  
  label2:
    ... 


4) Multiple IFs vs Seperated IFs
=======================================================

 There can be two kinds of "several IFs": Multiple Ifs (if, else if, else)
 and seperated ifs:

 MULTIPLE IF:
                     
              /-----(if)------\
             /                 \
 -----(ifStmt)----(else if)----( )------ 
             \                 / 
              \-----(else)----/



SEPARATED IFS:

----(ifStmt)--------------()----(ifStmt)---------()------
          \              /          \           /
           \----------- /            \---------/


4.1) Multiple IFS and Seperated IFs in Jimple:
======================================================
A multiple-If looks like this in Jimple (compare Section3, the Jimpelised If/IfElse/Else)

             								actions of else-clause							
 ---(!b0)----true--->(!b1)----true------------>(stm2)-------------->(label2)----->
 	  \					\                                              / /
 	   \				 \         actions of else-if-clause          / /
 	    \				  \------------------->(stm1)----------------/ /
       	 \                                                            /
       	  \                        actions of if-clause              /
           \---------------------------------->(stm01)--------------/

















{'fraction_non_alphanumeric': 0.24418194640338506, 'fraction_numerical': 0.01181241184767278, 'mean_word_length': 1.4442050840155105, 'pattern_counts': {'":': 1, '<': 13, '<?xml version=': 0, '>': 31, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 19, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4145000', 'n_tokens_mistral': 1615, 'n_tokens_neox': 1469, 'n_words': 427}