Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | n/a |
0 / 0 |
n/a |
0 / 0 |
CRAP | n/a |
0 / 0 |
1 | <?php |
2 | |
3 | namespace MediaWiki\Extension\DiscussionTools; |
4 | |
5 | use MediaWiki\Extension\DiscussionTools\ThreadItem\CommentItem; |
6 | use MediaWiki\Extension\DiscussionTools\ThreadItem\HeadingItem; |
7 | use MediaWiki\Extension\DiscussionTools\ThreadItem\ThreadItem; |
8 | |
9 | /** |
10 | * Groups thread items (headings and comments) generated by parsing a discussion page. |
11 | */ |
12 | interface ThreadItemSet { |
13 | /** |
14 | * @param ThreadItem $item |
15 | * @internal Only used by CommentParser |
16 | */ |
17 | public function addThreadItem( ThreadItem $item ); |
18 | |
19 | /** |
20 | * @return bool |
21 | * @internal Only used by CommentParser |
22 | */ |
23 | public function isEmpty(): bool; |
24 | |
25 | /** |
26 | * @param ThreadItem $item |
27 | * @internal Only used by CommentParser |
28 | */ |
29 | public function updateIdAndNameMaps( ThreadItem $item ); |
30 | |
31 | /** |
32 | * Get all discussion comments (and headings) within a DOM subtree. |
33 | * |
34 | * This returns a flat list, use getThreads() to get a tree structure starting at section headings. |
35 | * |
36 | * For example, for a MediaWiki discussion like this (we're dealing with HTML DOM here, |
37 | * the wikitext syntax is just for illustration): |
38 | * |
39 | * == A == |
40 | * B. ~~~~ |
41 | * : C. |
42 | * : C. ~~~~ |
43 | * :: D. ~~~~ |
44 | * ::: E. ~~~~ |
45 | * ::: F. ~~~~ |
46 | * : G. ~~~~ |
47 | * H. ~~~~ |
48 | * : I. ~~~~ |
49 | * |
50 | * This function would return a structure like: |
51 | * |
52 | * [ |
53 | * HeadingItem( { level: 0, range: (h2: A) } ), |
54 | * CommentItem( { level: 1, range: (p: B) } ), |
55 | * CommentItem( { level: 2, range: (li: C, li: C) } ), |
56 | * CommentItem( { level: 3, range: (li: D) } ), |
57 | * CommentItem( { level: 4, range: (li: E) } ), |
58 | * CommentItem( { level: 4, range: (li: F) } ), |
59 | * CommentItem( { level: 2, range: (li: G) } ), |
60 | * CommentItem( { level: 1, range: (p: H) } ), |
61 | * CommentItem( { level: 2, range: (li: I) } ) |
62 | * ] |
63 | * |
64 | * @return ThreadItem[] Thread items |
65 | */ |
66 | public function getThreadItems(): array; |
67 | |
68 | /** |
69 | * Same as getFlatThreadItems, but only returns the CommentItems |
70 | * |
71 | * @return CommentItem[] Comment items |
72 | */ |
73 | public function getCommentItems(): array; |
74 | |
75 | /** |
76 | * Find ThreadItems by their name |
77 | * |
78 | * This will usually return a single-element array, but it may return multiple comments if they're |
79 | * indistinguishable by name. In that case, use their IDs to disambiguate. |
80 | * |
81 | * @param string $name Name |
82 | * @return ThreadItem[] Thread items, empty array if not found |
83 | */ |
84 | public function findCommentsByName( string $name ): array; |
85 | |
86 | /** |
87 | * Find a ThreadItem by its ID |
88 | * |
89 | * @param string $id ID |
90 | * @return ThreadItem|null Thread item, null if not found |
91 | */ |
92 | public function findCommentById( string $id ): ?ThreadItem; |
93 | |
94 | /** |
95 | * Group discussion comments into threads and associate replies to original messages. |
96 | * |
97 | * Each thread must begin with a heading. Original messages in the thread are treated as replies to |
98 | * its heading. Other replies are associated based on the order and indentation level. |
99 | * |
100 | * WARNING: Sub-headings are included twice in this tree, once as the child item of the |
101 | * "parent" heading, and once again in the root object. |
102 | * |
103 | * Note that the objects in `comments` are extended in-place with the additional data. |
104 | * |
105 | * For example, for a MediaWiki discussion like this (we're dealing with HTML DOM here, |
106 | * the wikitext syntax is just for illustration): |
107 | * |
108 | * == A == |
109 | * B. ~~~~ |
110 | * : C. |
111 | * : C. ~~~~ |
112 | * :: D. ~~~~ |
113 | * ::: E. ~~~~ |
114 | * ::: F. ~~~~ |
115 | * : G. ~~~~ |
116 | * H. ~~~~ |
117 | * : I. ~~~~ |
118 | * |
119 | * This function would return a structure like: |
120 | * |
121 | * [ |
122 | * HeadingItem( { level: 0, range: (h2: A), replies: [ |
123 | * CommentItem( { level: 1, range: (p: B), replies: [ |
124 | * CommentItem( { level: 2, range: (li: C, li: C), replies: [ |
125 | * CommentItem( { level: 3, range: (li: D), replies: [ |
126 | * CommentItem( { level: 4, range: (li: E), replies: [] } ), |
127 | * CommentItem( { level: 4, range: (li: F), replies: [] } ), |
128 | * ] } ), |
129 | * ] } ), |
130 | * CommentItem( { level: 2, range: (li: G), replies: [] } ), |
131 | * ] } ), |
132 | * CommentItem( { level: 1, range: (p: H), replies: [ |
133 | * CommentItem( { level: 2, range: (li: I), replies: [] } ), |
134 | * ] } ), |
135 | * ] } ) |
136 | * ] |
137 | * |
138 | * @return HeadingItem[] Tree structure of comments, top-level items are the headings. |
139 | */ |
140 | public function getThreads(): array; |
141 | |
142 | /** |
143 | * Same as #getThreads, but without the duplicate sub-headings described in the |
144 | * documentation of that method. |
145 | * |
146 | * @return HeadingItem[] Tree structure of comments, top-level items are the headings. |
147 | */ |
148 | public function getThreadsStructured(): array; |
149 | } |