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> </td><td nowrap="nowrap">{@code --quiet}</td><td> </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> </td><td nowrap="nowrap">{@code --global}</td><td> </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> </td><td nowrap="nowrap">{@code --print}</td><td> </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> </td><td nowrap="nowrap">{@code --lineNumber}</td><td> </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> </td><td nowrap="nowrap">{@code --ignoreCase}</td><td> </td><td>Use case insensitive pattern matching.</td></tr> 052 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -s}</td><td> </td><td nowrap="nowrap">{@code --substitute}</td><td> </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> </td><td nowrap="nowrap">{@code --append}</td><td> </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> </td><td nowrap="nowrap">{@code --insert}</td><td> </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> </td><td nowrap="nowrap">{@code --change}</td><td> </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> </td><td nowrap="nowrap">{@code --delete}</td><td> </td><td>Delete the matched line.</td></tr> 070 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -y}</td><td> </td><td nowrap="nowrap">{@code --translate}</td><td> </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> : </td><td nowrap="nowrap">{@code String}</td><td> </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> : </td><td nowrap="nowrap">{@code String}</td><td> </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> : </td><td nowrap="nowrap">{@code String}</td><td> </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> : </td><td nowrap="nowrap">{@code String}</td><td> </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> : </td><td nowrap="nowrap">{@code String}</td><td> </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> : </td><td nowrap="nowrap">{@code int...}</td><td> </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> : </td><td nowrap="nowrap">{@code String...}</td><td> </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> : </td><td nowrap="nowrap">{@code SedOptions}</td><td> </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> </td><td nowrap="nowrap">{@code --quiet}</td><td> </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> </td><td nowrap="nowrap">{@code --global}</td><td> </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> </td><td nowrap="nowrap">{@code --print}</td><td> </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> </td><td nowrap="nowrap">{@code --lineNumber}</td><td> </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> </td><td nowrap="nowrap">{@code --ignoreCase}</td><td> </td><td>Use case insensitive pattern matching.</td></tr> 333 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -s}</td><td> </td><td nowrap="nowrap">{@code --substitute}</td><td> </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> </td><td nowrap="nowrap">{@code --append}</td><td> </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> </td><td nowrap="nowrap">{@code --insert}</td><td> </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> </td><td nowrap="nowrap">{@code --change}</td><td> </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> </td><td nowrap="nowrap">{@code --delete}</td><td> </td><td>Delete the matched line.</td></tr> 351 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -y}</td><td> </td><td nowrap="nowrap">{@code --translate}</td><td> </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}