1	<?php
2
3	namespace MediaWiki\Diff\TextDiffer;
4
5	use MediaWiki\Output\OutputPage;
6
7	/**
8	* An interface for parts of a diff page view which represent changes to text
9	*
10	* @since 1.41
11	*/
12	interface TextDiffer {
13	/**
14	* The HTML returned is an ordinary block
15	*/
16	public const CONTEXT_PLAIN = 'plain';
17
18	/**
19	* The HTML returned is zero or more table rows
20	*/
21	public const CONTEXT_ROW = 'row';
22
23	/**
24	* The return value is plain text and should be wrapped in a <pre>
25	*/
26	public const CONTEXT_PRE = 'pre';
27
28	/**
29	* Get a stable unique name to identify this differ in a cache key.
30	*/
31	public function getName(): string;
32
33	/**
34	* Get the supported format names
35	*
36	* @return string[]
37	*/
38	public function getFormats(): array;
39
40	/**
41	* Determine whether we support the specified format
42	*
43	* @param string $format
44	* @return bool
45	*/
46	public function hasFormat( string $format ): bool;
47
48	/**
49	* Get the context for a given format. Returns one of the CONTEXT_* constants.
50	*
51	* @param string $format
52	* @return string
53	*/
54	public function getFormatContext( string $format );
55
56	/**
57	* Make the context consistent by adding a colspan=4 wrapper around plain
58	* HTML output.
59	*
60	* @param string $format
61	* @param string $diffText
62	* @return string
63	*/
64	public function addRowWrapper( string $format, string $diffText ): string;
65
66	/**
67	* Generate a diff comparing $oldText with $newText.
68	* The result must be passed through localize() before being sent to the user.
69	*
70	* @param string $oldText
71	* @param string $newText
72	* @param string $format
73	* @return string
74	*/
75	public function render( string $oldText, string $newText, string $format ): string;
76
77	/**
78	* Render a diff in multiple formats.
79	* The results must be passed through localize() before being sent to the user.
80	*
81	* @param string $oldText
82	* @param string $newText
83	* @param string[] $formats
84	* @return array An array with the format in the key and the diff in the value.
85	*/
86	public function renderBatch( string $oldText, string $newText, array $formats ): array;
87
88	/**
89	* Modify the OutputPage, adding any headers required by the specified format.
90	*
91	* @param OutputPage $out
92	* @param string $format
93	* @return void
94	*/
95	public function addModules( OutputPage $out, string $format ): void;
96
97	/**
98	* Get additional cache keys required by the specified formats.
99	*
100	* The result should have unique string keys, so that cache keys can be
101	* deduplicated.
102	*
103	* @param string[] $formats
104	* @return array<string,string>
105	*/
106	public function getCacheKeys( array $formats ): array;
107
108	/**
109	* Expand messages in the diff text using the current MessageLocalizer.
110	*
111	* Perform any other necessary post-cache transformations.
112	*
113	* @param string $format
114	* @param string $diff
115	* @param array $options An associative array of options, may contain:
116	*   - reducedLineNumbers: If true, remove "line 1" but allow other line numbers
117	* @return string
118	*/
119	public function localize( string $format, string $diff, array $options = [] ): string;
120
121	/**
122	* Get table prefixes for the specified format. These are HTML fragments
123	* placed above all slot diffs. The key should be a string, used for sorting
124	* and deduplication.
125	*
126	* @param string $format
127	* @return array
128	*/
129	public function getTablePrefixes( string $format ): array;
130
131	/**
132	* Given a format, get a list of formats which can be generated at the same
133	* time with minimal additional CPU cost.
134	*
135	* @param string $format
136	* @return string[]
137	*/
138	public function getPreferredFormatBatch( string $format ): array;
139	}