summaryrefslogtreecommitdiffstats
path: root/debian/uncrustify-trinity/uncrustify-trinity-0.74.0/documentation/threads.txt
blob: f6ed4edd13b63c3521c7972ef9ba01b45b97e5da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

Notes on how to deal with the wicked corner case that is C/C++
preprocessor #if magic.  None of this is actually implemented.

Languages not affected:
 - D
 - Java
 - ECMA (Java Script)

Langauges affected:
 - C
 - C++
 - C#
 - Vala
 - Pawn
 - Objective C/C++


Threads of code are created for functions that navigate the tokens.
There is the master list of the raw tokens parsed out.

There is at least one thread, which, in the absense of any #if statements, is
the same as the raw token list.

In the threads, a BARRIER is placed where ever code cannot move past.
This represents and #if or #else statement.
Normally, the barriers are skipped when navigating code. Only when removing a
newline does the code need to check for a barrier.

For #if statements without an #else, there is an implicit #else added that contains
nothing.

// example 1
a
#if X
b
#endif
c

Thread
       #if   #endif
       V     V
0 - a -+- b -+- c
       |     |
1      +-----+  <- empty else path (ie, for '#if 0')

Max depth = 2


// example 2
a
#if X
b
#else
c
#endif
d
       #if   #endif
       V     V
0 - a -+- b -+- d
       |     |
1      +- c -+   <- else path

Max depth = 2


// example 3
a
#if X
b
#elif Y
c
#elif Z
d
#else
e
#endif
f
#if A
g
#endif
h
       #if X #endif          #if A
       V     V               V
0 - a -+- b -+- f -----------+- g -+- h
       |     |               |     |
1      +- c -+   <- elif Y   +-----+   <- empty else
       |     |
2      +- d -+   <- elif Z
       |     |
3      +- e -+   <- else

Max depth = 4

The detection routines need to be executed once for each thread, up to the maximum
thread depth.  Note that the typical maximum thread depth is going to be 2-3.

0 - a - b - f - g - h
1 - a - c - f ----- h
2 - a - d - f - g - h
3 - a - e - f - g - h

The general rule is that if the current thread exceed the max, thread 0 is used.

Identification is the primary use for the threads.
The secondary use is indentation.  The indentation of each token at each thread
level is recorded.
The maximum indentation for the token is used, assuming the thread is without
error. ('#if 0' commented out code that is bad may not be handled.)

I won't know if this will work for sure until I try it.