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	}