1	<?php
2	declare( strict_types = 1 );
3
4	namespace Wikimedia\Parsoid\Ext;
5
6	use Wikimedia\Parsoid\Fragments\PFragment;
7
8	/**
9	* An object which implements Arguments provides a way to parse or
10	* interpret its contents as arguments to a PFragmentHandler or
11	* other transclusion.
12	*
13	* There are two primary modes of parsing arguments, and both must
14	* be supported:
15	* - "Ordered" arguments: arguments are provided as an ordered list
16	*   of PFragment values.  They are not split on `=` and `=` is not
17	*   treated as a special character.  (This is traditionally how
18	*   arguments were provided to parser functions.)
19	* - "Named" arguments: arguments are provided as a map from string
20	*   'names' to PFragment values.  Values are split on the first `=`
21	*   character in their tokenized-but-unexpanded form, then keys are
22	*   expanded. Strip markers in the key name cause the key to be
23	*   discarded.  For example:
24	*    - `{{foo|{{1x|a=b}}=c}}` assigns the value `c` to the key `a=b`
25	*    - `{{foo|<nowiki>a=</nowiki>b=c}}` assigns no keys
26	*   Any unnamed parameters (whose tokenized-but-unexpanded values
27	*   contain no `=`) are assigned consecutive numeric string
28	*   names starting with "1".  In case of duplicate keys, the
29	*   one ordered last wins.
30	*
31	* As a convenience, both primary accessors provide a "expand and
32	* trim" boolean which defaults to `true`.  This calls
33	* PFragment::expand() and then PFragment::trim() on each value before
34	* returning it, which is a common argument-handling pattern.  In
35	* cases where lazy or untrimmed handling of arguments is desired,
36	* call the accessor with `false`, and then manually expand/trim
37	* specific values as needed.  (Note that key values for named
38	* arguments are always "expanded and trimmed".)
39	*
40	* Often editors will want to pass "raw text" values to a fragment
41	* handler, which may include "special" characters like `=`, `|`, and
42	* `&`.  The PFragment::toRawText() helper method can be used on
43	* (preferrably unexpanded) argument values to extract a "raw text"
44	* string; this implements various conventions commonly used for
45	* passing raw text.
46	*
47	* Not implemented yet, but expected in the future:
48	*
49	* 1. A third accessor will be added, which will provide access to
50	* named arguments as a list of tuples containing:
51	* - The parsed key, as a string
52	* - The unexpanded-and-untrimmed key, as a PFragment including the `=`,
53	*   or null for unnamed keys
54	* - The unexpanded-and-untrimmed value
55	*
56	* That is, the list will provide the original argument order, including
57	* the contents of arguments with duplicate or invalid keys, and the
58	* list contents will allow recreation of the original argument text
59	* by concatenating the unexpanded key with the unexpanded value.
60	*
61	* 2. As an additional Parsoid-only feature of both ordered and named
62	* arguments, any argument whose trimmed value is a PFragment
63	* implementing the Arguments interface will have those arguments spliced
64	* into the argument list at that location (T390347).
65	*/
66	interface Arguments {
67
68	/**
69	* Return a list of ordered arguments.
70	* @param ParsoidExtensionAPI $extApi
71	* @param bool|list<bool> $expandAndTrim If true (the default) the
72	*  return arguments each have PFragment::expand() and
73	*  PFragment::trim() invoked on them. If false, the arguments are
74	*  provided as they exist in the source: unexpanded and
75	*  untrimmed.  In addition to passing a boolean, an array of
76	*  booleans can be passed, which specifies the desired value of
77	*  $expandAndTrim for each ordered argument; missing entries
78	*  default to `true`.
79	* @return list<PFragment> The ordered argument list.  The first
80	*  argument is at index 0, as is conventional for PHP arrays.
81	*/
82	public function getOrderedArgs(
83	ParsoidExtensionAPI $extApi,
84	$expandAndTrim = true
85	): array;
86
87	/**
88	* Return a map of named arguments.
89	*
90	* Unnamed arguments are assigned numeric "names" starting at 1.
91	*
92	* @note Beware that PHP will convert any numeric argument name
93	* which is an integer to a `int`, so the key type of the returned
94	* map is `string|int`.
95	*
96	* @param ParsoidExtensionAPI $extApi
97	* @param bool|array<string|int,bool> $expandAndTrim If true (the
98	*  default) the return argument values each have
99	*  PFragment::expand() and PFragment::trim() invoked on them. If
100	*  false, the argument values are provided as they exist in the
101	*  source: unexpanded and untrimmed.  In addition to passing a
102	*  boolean, an map of booleans can be passed, which specifies the
103	*  desired value of $expandAndTrim for each named argument;
104	*  missing entries default to `true`.
105	* @return array<string|int,PFragment> The named argument map.
106	*  Note that the first unnamed argument corresponds to the key 1,
107	*  not 0.
108	*/
109	public function getNamedArgs(
110	ParsoidExtensionAPI $extApi,
111	$expandAndTrim = true
112	): array;
113	}