001package org.unix4j.unix;
002
003import org.unix4j.command.CommandInterface;
004
005import org.unix4j.unix.sed.SedFactory;
006import org.unix4j.unix.sed.SedOption;
007import org.unix4j.unix.sed.SedOptions;
008import org.unix4j.unix.sed.SedOptionSets;
009
010/**
011 * Non-instantiable module with inner types making up the <b>sed</b> command.
012 * <p>
013 * <b>NAME</b>
014 * <p>
015 * sed - stream editor for filtering and transforming text 
016 * <p>
017 * <b>SYNOPSIS</b>
018 * <p>
019 * <table>
020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed <args>}</td></tr>
021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed <script>}</td></tr>
022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed <regexp> <replacement>}</td></tr>
023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed <regexp> <replacement> <occurrence>}</td></tr>
024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed [-ngplIsaicdy] <regexp>}</td></tr>
025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed [-ngplIsaicdy] <string1> <string2>}</td></tr>
026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code sed [-ngplIsaicdy] <string1> <string2> <occurrence>}</td></tr>
027 * </table>
028 * <p>
029 * See {@link Interface} for the corresponding command signature methods.
030 * <p>
031 * <b>DESCRIPTION</b>
032 * <p>
033 * <p>  Sed is a stream editor. A stream editor is used to perform basic text   transformations on an input stream (a file or input from a pipeline).   While in some ways similar to an editor which permits scripted edits    (such as ed), sed works by making only one pass over the input(s),      and is consequently more efficient. But it is sed's ability to filter   text in a pipeline which particularly distinguishes it from other       types of editors.</p><p>        <b>Some examples:</b>   <br/>   <pre>input day into sed("s/day/night/") This will output "night"</pre>  <br/>   <pre>input "day and night" into sed("s/\\sand\\s/-to-/") This will output "day-to-night"</pre>  (Note the use of \s whitespace character).      <br/>   Java regular expressions are used for searching and replacing. For an   overview of the Java pattern matching, and substitution, please see the {@link java.util.regex.Pattern} documentation.</p>
034 * 
035 * <p>
036 * <b>Options</b>
037 * <p>
038 * The following options are supported:
039 * <p>
040 * <table>
041 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --quiet}</td><td>&nbsp;</td><td>Suppress the default output (in which each line, after it is 
042                        examined for editing, is written to standard output). Only lines 
043                        explicitly selected for output are written.</td></tr>
044 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -g}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --global}</td><td>&nbsp;</td><td>Globally substitute for all non-overlapping instances of the regexp 
045                        rather than just the first one. 
046                        <p>
047                        (This option is ignored if the occurrence operand is specified).</td></tr>
048 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -p}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --print}</td><td>&nbsp;</td><td>Write the matched line to standard output.</td></tr>
049 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --lineNumber}</td><td>&nbsp;</td><td>Writes the current line number on a separate line to the standard 
050                        output.</td></tr>
051 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -I}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --ignoreCase}</td><td>&nbsp;</td><td>Use case insensitive pattern matching.</td></tr>
052 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -s}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --substitute}</td><td>&nbsp;</td><td>Substitutes the replacement string for instances of the regexp in 
053                        the matched line.
054<p>
055                        The characters "$0" appearing in the replacement are replaced
056                        by the line matching the regexp.  The characters "$n", where n is a
057                        digit other than zero, are replaced by the text matched by the
058                        corresponding backreference expression (aka group).  The special
059                        meaning of "$n" in this context can be suppressed by preceding it
060                        by a backslash.
061<p>
062                        A line can be split by substituting a newline ('\n') into it. 
063                        <p>
064                        A substitution is considered to have been performed even if the 
065                        replacement string is identical to the string that it replaces.</td></tr>
066 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -a}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --append}</td><td>&nbsp;</td><td>Append string2 as a separate line after the matched line.</td></tr>
067 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -i}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --insert}</td><td>&nbsp;</td><td>Insert string2 as a separate line before the matched line.</td></tr>
068 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --change}</td><td>&nbsp;</td><td>Write string2 as a separate line instead of the matched line.</td></tr>
069 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -d}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --delete}</td><td>&nbsp;</td><td>Delete the matched line.</td></tr>
070 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -y}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --translate}</td><td>&nbsp;</td><td>Replace all occurrences of characters in string1 with the 
071                        corresponding characters in string2. If the number of characters in 
072                        the two strings are not equal, or if any of the characters in 
073                        string1 appear more than once, the results are undefined.</td></tr>
074 * </table>
075 * <p>
076 * <b>OPERANDS</b>
077 * <p>
078 * The following operands are supported:
079 * <p>
080 * <table>
081 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <script>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>Sed script as one string, such as "s/original/replacement/g".</td></tr>
082 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <regexp>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>Regular expression matched against a line.</td></tr>
083 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <string1>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>Regular expression matched against a line for all commands except 
084                        for command y where string1 contains the source characters for the 
085                        translation.</td></tr>
086 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <replacement>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>Replacement string for substitute command. The characters "$0"
087                        appearing in the replacement are replaced by the line matching
088                        the regexp.  The characters "$n", where n is a digit other than zero,
089                        are replaced by the text matched by the corresponding backreference
090                        expression (aka group).  The special meaning of "$n" in this context
091                        can be suppressed by preceding it by a backslash.</td></tr>
092 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <string2>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>Replacement string for substitute command s; appended, inserted or
093                        changed text for a, i and c command; destination characters for
094                        translate command y; ignored by all other commands.
095                        <p>
096                        If string2 is a replacement string for the substitute command: the
097                        characters "$0" appearing in the replacement are replaced
098                        by the line matching the regexp; the characters "$n", where n is a
099                        digit other than zero, are replaced by the text matched by the
100                        corresponding backreference expression (aka group).  The special
101                        meaning of "$n" in this context can be suppressed by preceding it
102                        by a backslash.
103<p>
104                        (This operand only applies to the commands s, a, i, c and y and is 
105                        ignored by all other commands).</td></tr>
106 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <occurrence>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code int...}</td><td>&nbsp;</td><td>Substitute for the given occurrences only of the regexp found within 
107                        the matched string; the occurrence indices are one-based. If empty 
108                        or omitted, all occurrences are substituted.
109                        <p>
110                        (This operand only applies to the substitute command and is ignored
111                        by all other commands).</td></tr>
112 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <args>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String...}</td><td>&nbsp;</td><td>String arguments defining the options and operands for the command. 
113                        Options can be specified by acronym (with a leading dash "-") or by 
114                        long name (with two leading dashes "--"). Operands other than the
115                        default "--script" operand have to be prefixed with the operand name
116                        (e.g. "--occurrence" for subsequent occurrence indices).</td></tr>
117 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code SedOptions}</td><td>&nbsp;</td><td>Sed options and commands</td></tr>
118 * </table>
119 */
120public final class Sed {
121        /**
122         * The "sed" command name.
123         */
124        public static final String NAME = "sed";
125
126        /**
127         * Interface defining all method signatures for the "sed" command.
128         * 
129         * @param <R>
130         *            the generic return type for all command signature methods
131         *            to support different implementor types; the methods of a 
132         *            command factory for instance returns a command instance; 
133         *            command builders can also implement this interface, but their
134         *            methods return the builder itself enabling for chained method
135         *            invocation to create joined commands
136         */
137        public static interface Interface<R> extends CommandInterface<R> {
138                /**
139                 * Executes the sed script specified by the given arguments and writes
140                        the result to the standard output. 
141                        <p>
142                        Options can be specified by acronym (with a leading dash "-") or by 
143                        long name (with two leading dashes "--"). Operands other than the 
144                        default "--script" operand have to be prefixed with the operand name.
145                 *
146                 * @param args String arguments defining the options and operands for the command. 
147                        Options can be specified by acronym (with a leading dash "-") or by 
148                        long name (with two leading dashes "--"). Operands other than the
149                        default "--script" operand have to be prefixed with the operand name
150                        (e.g. "--occurrence" for subsequent occurrence indices).
151                 * @return the generic type {@code <R>} defined by the implementing class;
152                 *         the command itself returns no value and writes its result to the
153                 *         standard output; see class level parameter comments for more 
154                 *         details
155                 */
156                R sed(String... args);
157                /**
158                 * Executes the given sed script, such as "s/original/replacement/g".
159                 *
160                 * @param script Sed script as one string, such as "s/original/replacement/g".
161                 * @return the generic type {@code <R>} defined by the implementing class;
162                 *         the command itself returns no value and writes its result to the
163                 *         standard output; see class level parameter comments for more 
164                 *         details
165                 */
166                R sed(String script);
167                /**
168                 * Substitutes the replacement string for instances of the regexp in 
169                        the matched line.
170                        <p>
171                        The characters "$0" appearing in the replacement are replaced
172                        by the line matching the regexp.  The characters "$n", where n is a
173                        digit other than zero, are replaced by the text matched by the
174                        corresponding backreference expression (aka group).  The special
175                        meaning of "$n" in this context can be suppressed by preceding it
176                        by a backslash.
177<p>
178                        A line can be split by substituting a newline ('\n') into it. 
179                        <p>
180                        A substitution is considered to have been performed even if the 
181                        replacement string is identical to the string that it replaces.
182                 *
183                 * @param regexp Regular expression matched against a line.
184                 * @param replacement Replacement string for substitute command. The characters "$0"
185                        appearing in the replacement are replaced by the line matching
186                        the regexp.  The characters "$n", where n is a digit other than zero,
187                        are replaced by the text matched by the corresponding backreference
188                        expression (aka group).  The special meaning of "$n" in this context
189                        can be suppressed by preceding it by a backslash.
190                 * @return the generic type {@code <R>} defined by the implementing class;
191                 *         the command itself returns no value and writes its result to the
192                 *         standard output; see class level parameter comments for more 
193                 *         details
194                 */
195                R sed(String regexp, String replacement);
196                /**
197                 * Substitutes the replacement string for instances of the regexp in 
198                        the matched line. Only the given occurrences of the regexp found 
199                        within the matched string are substituted.
200<p>
201                        The characters "$0" appearing in the replacement are replaced
202                        by the line matching the regexp.  The characters "$n", where n is a
203                        digit other than zero, are replaced by the text matched by the
204                        corresponding backreference expression (aka group).  The special
205                        meaning of "$n" in this context can be suppressed by preceding it
206                        by a backslash.
207<p>
208                        A line can be split by substituting a newline ('\n') into it. 
209                        <p>
210                        A substitution is considered to have been performed even if the 
211                        replacement string is identical to the string that it replaces.
212                 *
213                 * @param regexp Regular expression matched against a line.
214                 * @param replacement Replacement string for substitute command. The characters "$0"
215                        appearing in the replacement are replaced by the line matching
216                        the regexp.  The characters "$n", where n is a digit other than zero,
217                        are replaced by the text matched by the corresponding backreference
218                        expression (aka group).  The special meaning of "$n" in this context
219                        can be suppressed by preceding it by a backslash.
220                 * @param occurrence Substitute for the given occurrences only of the regexp found within 
221                        the matched string; the occurrence indices are one-based. If empty 
222                        or omitted, all occurrences are substituted.
223                        <p>
224                        (This operand only applies to the substitute command and is ignored
225                        by all other commands).
226                 * @return the generic type {@code <R>} defined by the implementing class;
227                 *         the command itself returns no value and writes its result to the
228                 *         standard output; see class level parameter comments for more 
229                 *         details
230                 */
231                R sed(String regexp, String replacement, int... occurrence);
232                /**
233                 * Executes the sed command specified by the given options or executes
234                        the print command p if no command option has been declared.
235                 *
236                 * @param options Sed options and commands
237                 * @param regexp Regular expression matched against a line.
238                 * @return the generic type {@code <R>} defined by the implementing class;
239                 *         the command itself returns no value and writes its result to the
240                 *         standard output; see class level parameter comments for more 
241                 *         details
242                 */
243                R sed(SedOptions options, String regexp);
244                /**
245                 * Executes the sed command specified by the given options or executes
246                        the substitute command s if no command option has been declared.
247                 *
248                 * @param options Sed options and commands
249                 * @param string1 Regular expression matched against a line for all commands except 
250                        for command y where string1 contains the source characters for the 
251                        translation.
252                 * @param string2 Replacement string for substitute command s; appended, inserted or
253                        changed text for a, i and c command; destination characters for
254                        translate command y; ignored by all other commands.
255                        <p>
256                        If string2 is a replacement string for the substitute command: the
257                        characters "$0" appearing in the replacement are replaced
258                        by the line matching the regexp; the characters "$n", where n is a
259                        digit other than zero, are replaced by the text matched by the
260                        corresponding backreference expression (aka group).  The special
261                        meaning of "$n" in this context can be suppressed by preceding it
262                        by a backslash.
263<p>
264                        (This operand only applies to the commands s, a, i, c and y and is 
265                        ignored by all other commands).
266                 * @return the generic type {@code <R>} defined by the implementing class;
267                 *         the command itself returns no value and writes its result to the
268                 *         standard output; see class level parameter comments for more 
269                 *         details
270                 */
271                R sed(SedOptions options, String string1, String string2);
272                /**
273                 * Executes the sed command specified by the given options or executes
274                        the substitute command s if no command option has been declared.
275                        <p>
276                        The string1 operand usually contains the regular expression matched 
277                        against a line for all commands except for command y where string1 
278                        contains the source characters for the translation.
279                        <p>
280                        The string2 operand contains the replacement string for the 
281                        substitute command s. It contains the appended, inserted or changed 
282                        text for the commands a, i and c, respectively, and the destination 
283                        characters for the translate command y. All other commands ignore
284                        the string2 operand.
285                 *
286                 * @param options Sed options and commands
287                 * @param string1 Regular expression matched against a line for all commands except 
288                        for command y where string1 contains the source characters for the 
289                        translation.
290                 * @param string2 Replacement string for substitute command s; appended, inserted or
291                        changed text for a, i and c command; destination characters for
292                        translate command y; ignored by all other commands.
293                        <p>
294                        If string2 is a replacement string for the substitute command: the
295                        characters "$0" appearing in the replacement are replaced
296                        by the line matching the regexp; the characters "$n", where n is a
297                        digit other than zero, are replaced by the text matched by the
298                        corresponding backreference expression (aka group).  The special
299                        meaning of "$n" in this context can be suppressed by preceding it
300                        by a backslash.
301<p>
302                        (This operand only applies to the commands s, a, i, c and y and is 
303                        ignored by all other commands).
304                 * @param occurrence Substitute for the given occurrences only of the regexp found within 
305                        the matched string; the occurrence indices are one-based. If empty 
306                        or omitted, all occurrences are substituted.
307                        <p>
308                        (This operand only applies to the substitute command and is ignored
309                        by all other commands).
310                 * @return the generic type {@code <R>} defined by the implementing class;
311                 *         the command itself returns no value and writes its result to the
312                 *         standard output; see class level parameter comments for more 
313                 *         details
314                 */
315                R sed(SedOptions options, String string1, String string2, int... occurrence);
316        }
317
318        /**
319         * Options for the "sed" command: {@link SedOption#quiet n}, {@link SedOption#global g}, {@link SedOption#print p}, {@link SedOption#lineNumber l}, {@link SedOption#ignoreCase I}, {@link SedOption#substitute s}, {@link SedOption#append a}, {@link SedOption#insert i}, {@link SedOption#change c}, {@link SedOption#delete d}, {@link SedOption#translate y}.
320         * <p> 
321 * <table>
322 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --quiet}</td><td>&nbsp;</td><td>Suppress the default output (in which each line, after it is 
323                        examined for editing, is written to standard output). Only lines 
324                        explicitly selected for output are written.</td></tr>
325 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -g}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --global}</td><td>&nbsp;</td><td>Globally substitute for all non-overlapping instances of the regexp 
326                        rather than just the first one. 
327                        <p>
328                        (This option is ignored if the occurrence operand is specified).</td></tr>
329 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -p}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --print}</td><td>&nbsp;</td><td>Write the matched line to standard output.</td></tr>
330 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --lineNumber}</td><td>&nbsp;</td><td>Writes the current line number on a separate line to the standard 
331                        output.</td></tr>
332 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -I}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --ignoreCase}</td><td>&nbsp;</td><td>Use case insensitive pattern matching.</td></tr>
333 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -s}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --substitute}</td><td>&nbsp;</td><td>Substitutes the replacement string for instances of the regexp in 
334                        the matched line.
335<p>
336                        The characters "$0" appearing in the replacement are replaced
337                        by the line matching the regexp.  The characters "$n", where n is a
338                        digit other than zero, are replaced by the text matched by the
339                        corresponding backreference expression (aka group).  The special
340                        meaning of "$n" in this context can be suppressed by preceding it
341                        by a backslash.
342<p>
343                        A line can be split by substituting a newline ('\n') into it. 
344                        <p>
345                        A substitution is considered to have been performed even if the 
346                        replacement string is identical to the string that it replaces.</td></tr>
347 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -a}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --append}</td><td>&nbsp;</td><td>Append string2 as a separate line after the matched line.</td></tr>
348 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -i}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --insert}</td><td>&nbsp;</td><td>Insert string2 as a separate line before the matched line.</td></tr>
349 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --change}</td><td>&nbsp;</td><td>Write string2 as a separate line instead of the matched line.</td></tr>
350 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -d}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --delete}</td><td>&nbsp;</td><td>Delete the matched line.</td></tr>
351 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -y}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --translate}</td><td>&nbsp;</td><td>Replace all occurrences of characters in string1 with the 
352                        corresponding characters in string2. If the number of characters in 
353                        the two strings are not equal, or if any of the characters in 
354                        string1 appear more than once, the results are undefined.</td></tr>
355 * </table>
356         */
357        public static final SedOptionSets Options = SedOptionSets.INSTANCE;
358
359        /**
360         * Singleton {@link SedFactory factory} instance for the "sed" command.
361         */
362        public static final SedFactory Factory = SedFactory.INSTANCE;
363
364        // no instances
365        private Sed() {
366                super();
367        }
368}