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