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 An ampersand ('&') appearing in the replacement is be replaced 056 by the line matching the regexp. The characters "\n", where n is a 057 digit, are replaced by the text matched by the corresponding 058 backreference expression. The special meaning of '&' and "\n" 059 in this context can be suppressed by preceding it by a backslash. 060<p> 061 A line can be split by substituting a newline ('\n') into it. 062 <p> 063 A substitution is considered to have been performed even if the 064 replacement string is identical to the string that it replaces.</td></tr> 065 * <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> 066 * <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> 067 * <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> 068 * <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> 069 * <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 070 corresponding characters in string2. If the number of characters in 071 the two strings are not equal, or if any of the characters in 072 string1 appear more than once, the results are undefined.</td></tr> 073 * </table> 074 * <p> 075 * <b>OPERANDS</b> 076 * <p> 077 * The following operands are supported: 078 * <p> 079 * <table> 080 * <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> 081 * <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> 082 * <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 083 for command y where string1 contains the source characters for the 084 translation.</td></tr> 085 * <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. An ampersand ('&') 086 appearing in the replacement string is replaced by the string 087 matching the regular expression. The characters "\n", where n is a 088 digit, are replaced by the text matched by the corresponding 089 backreference expression. The special meaning of '&' and "\n" in 090 this context can be suppressed by preceding it by a backslash.</td></tr> 091 * <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 092 changed text for a, i and c command; destination characters for 093 translate command y; ignored by all other commands. 094 <p> 095 If string2 is a replacement string for the substitute command: an 096 ampersand ('&') appearing in the replacement string is replaced 097 by the string matching the regular expression; the characters "\n", 098 where n is a digit, are replaced by the text matched by the 099 corresponding backreference expression. The special meaning of 100 '&' and "\n" in this context can be suppressed by preceding it 101 by a backslash. 102<p> 103 (This operand only applies to the commands s, a, i, c and y and is 104 ignored by all other commands).</td></tr> 105 * <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 106 the matched string; the occurrence indices are one-based. If empty 107 or omitted, all occurrences are substituted. 108 <p> 109 (This operand only applies to the substitute command and is ignored 110 by all other commands).</td></tr> 111 * <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. 112 Options can be specified by acronym (with a leading dash "-") or by 113 long name (with two leading dashes "--"). Operands other than the 114 default "--script" operand have to be prefixed with the operand name 115 (e.g. "--occurrence" for subsequent occurrence indices).</td></tr> 116 * <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> 117 * </table> 118 */ 119public final class Sed { 120 /** 121 * The "sed" command name. 122 */ 123 public static final String NAME = "sed"; 124 125 /** 126 * Interface defining all method signatures for the "sed" command. 127 * 128 * @param <R> 129 * the generic return type for all command signature methods 130 * to support different implementor types; the methods of a 131 * command factory for instance returns a command instance; 132 * command builders can also implement this interface, but their 133 * methods return the builder itself enabling for chained method 134 * invocation to create joined commands 135 */ 136 public static interface Interface<R> extends CommandInterface<R> { 137 /** 138 * Executes the sed script specified by the given arguments and writes 139 the result to the standard output. 140 <p> 141 Options can be specified by acronym (with a leading dash "-") or by 142 long name (with two leading dashes "--"). Operands other than the 143 default "--script" operand have to be prefixed with the operand name. 144 * 145 * @param args String arguments defining the options and operands for the command. 146 Options can be specified by acronym (with a leading dash "-") or by 147 long name (with two leading dashes "--"). Operands other than the 148 default "--script" operand have to be prefixed with the operand name 149 (e.g. "--occurrence" for subsequent occurrence indices). 150 * @return the generic type {@code <R>} defined by the implementing class; 151 * the command itself returns no value and writes its result to the 152 * standard output; see class level parameter comments for more 153 * details 154 */ 155 R sed(String... args); 156 /** 157 * Executes the given sed script, such as "s/original/replacement/g". 158 * 159 * @param script Sed script as one string, such as "s/original/replacement/g". 160 * @return the generic type {@code <R>} defined by the implementing class; 161 * the command itself returns no value and writes its result to the 162 * standard output; see class level parameter comments for more 163 * details 164 */ 165 R sed(String script); 166 /** 167 * Substitutes the replacement string for instances of the regexp in 168 the matched line. 169 <p> 170 An ampersand ('&') appearing in the replacement is be replaced 171 by the line matching the regexp. The characters "\n", where n is a 172 digit, are replaced by the text matched by the corresponding 173 backreference expression. The special meaning of '&' and "\n" 174 in this context can be suppressed by preceding it by a backslash. 175<p> 176 A line can be split by substituting a newline ('\n') into it. 177 <p> 178 A substitution is considered to have been performed even if the 179 replacement string is identical to the string that it replaces. 180 * 181 * @param regexp Regular expression matched against a line. 182 * @param replacement Replacement string for substitute command. An ampersand ('&') 183 appearing in the replacement string is replaced by the string 184 matching the regular expression. The characters "\n", where n is a 185 digit, are replaced by the text matched by the corresponding 186 backreference expression. The special meaning of '&' and "\n" in 187 this context can be suppressed by preceding it by a backslash. 188 * @return the generic type {@code <R>} defined by the implementing class; 189 * the command itself returns no value and writes its result to the 190 * standard output; see class level parameter comments for more 191 * details 192 */ 193 R sed(String regexp, String replacement); 194 /** 195 * Substitutes the replacement string for instances of the regexp in 196 the matched line. Only the given occurrences of the regexp found 197 within the matched string are substituted. 198 <p> 199 An ampersand ('&') appearing in the replacement is be replaced 200 by the line matching the regexp. The characters "\n", where n is a 201 digit, are replaced by the text matched by the corresponding 202 backreference expression. The special meaning of '&' and "\n" 203 in this context can be suppressed by preceding it by a backslash. 204<p> 205 A line can be split by substituting a newline ('\n') into it. 206 <p> 207 A substitution is considered to have been performed even if the 208 replacement string is identical to the string that it replaces. 209 * 210 * @param regexp Regular expression matched against a line. 211 * @param replacement Replacement string for substitute command. An ampersand ('&') 212 appearing in the replacement string is replaced by the string 213 matching the regular expression. The characters "\n", where n is a 214 digit, are replaced by the text matched by the corresponding 215 backreference expression. The special meaning of '&' and "\n" in 216 this context can be suppressed by preceding it by a backslash. 217 * @param occurrence Substitute for the given occurrences only of the regexp found within 218 the matched string; the occurrence indices are one-based. If empty 219 or omitted, all occurrences are substituted. 220 <p> 221 (This operand only applies to the substitute command and is ignored 222 by all other commands). 223 * @return the generic type {@code <R>} defined by the implementing class; 224 * the command itself returns no value and writes its result to the 225 * standard output; see class level parameter comments for more 226 * details 227 */ 228 R sed(String regexp, String replacement, int... occurrence); 229 /** 230 * Executes the sed command specified by the given options or executes 231 the print command p if no command option has been declared. 232 * 233 * @param options Sed options and commands 234 * @param regexp Regular expression matched against a line. 235 * @return the generic type {@code <R>} defined by the implementing class; 236 * the command itself returns no value and writes its result to the 237 * standard output; see class level parameter comments for more 238 * details 239 */ 240 R sed(SedOptions options, String regexp); 241 /** 242 * Executes the sed command specified by the given options or executes 243 the substitute command s if no command option has been declared. 244 * 245 * @param options Sed options and commands 246 * @param string1 Regular expression matched against a line for all commands except 247 for command y where string1 contains the source characters for the 248 translation. 249 * @param string2 Replacement string for substitute command s; appended, inserted or 250 changed text for a, i and c command; destination characters for 251 translate command y; ignored by all other commands. 252 <p> 253 If string2 is a replacement string for the substitute command: an 254 ampersand ('&') appearing in the replacement string is replaced 255 by the string matching the regular expression; the characters "\n", 256 where n is a digit, are replaced by the text matched by the 257 corresponding backreference expression. The special meaning of 258 '&' and "\n" in this context can be suppressed by preceding it 259 by a backslash. 260<p> 261 (This operand only applies to the commands s, a, i, c and y and is 262 ignored by all other commands). 263 * @return the generic type {@code <R>} defined by the implementing class; 264 * the command itself returns no value and writes its result to the 265 * standard output; see class level parameter comments for more 266 * details 267 */ 268 R sed(SedOptions options, String string1, String string2); 269 /** 270 * Executes the sed command specified by the given options or executes 271 the substitute command s if no command option has been declared. 272 <p> 273 The string1 operand usually contains the regular expression matched 274 against a line for all commands except for command y where string1 275 contains the source characters for the translation. 276 <p> 277 The string2 operand contains the replacement string for the 278 substitute command s. It contains the appended, inserted or changed 279 text for the commands a, i and c, respectively, and the destination 280 characters for the translate command y. All other commands ignore 281 the string2 operand. 282 * 283 * @param options Sed options and commands 284 * @param string1 Regular expression matched against a line for all commands except 285 for command y where string1 contains the source characters for the 286 translation. 287 * @param string2 Replacement string for substitute command s; appended, inserted or 288 changed text for a, i and c command; destination characters for 289 translate command y; ignored by all other commands. 290 <p> 291 If string2 is a replacement string for the substitute command: an 292 ampersand ('&') appearing in the replacement string is replaced 293 by the string matching the regular expression; the characters "\n", 294 where n is a digit, are replaced by the text matched by the 295 corresponding backreference expression. The special meaning of 296 '&' and "\n" in this context can be suppressed by preceding it 297 by a backslash. 298<p> 299 (This operand only applies to the commands s, a, i, c and y and is 300 ignored by all other commands). 301 * @param occurrence Substitute for the given occurrences only of the regexp found within 302 the matched string; the occurrence indices are one-based. If empty 303 or omitted, all occurrences are substituted. 304 <p> 305 (This operand only applies to the substitute command and is ignored 306 by all other commands). 307 * @return the generic type {@code <R>} defined by the implementing class; 308 * the command itself returns no value and writes its result to the 309 * standard output; see class level parameter comments for more 310 * details 311 */ 312 R sed(SedOptions options, String string1, String string2, int... occurrence); 313 } 314 315 /** 316 * 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}. 317 * <p> 318 * <table> 319 * <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 320 examined for editing, is written to standard output). Only lines 321 explicitly selected for output are written.</td></tr> 322 * <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 323 rather than just the first one. 324 <p> 325 (This option is ignored if the occurrence operand is specified).</td></tr> 326 * <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> 327 * <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 328 output.</td></tr> 329 * <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> 330 * <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 331 the matched line. 332 <p> 333 An ampersand ('&') appearing in the replacement is be replaced 334 by the line matching the regexp. The characters "\n", where n is a 335 digit, are replaced by the text matched by the corresponding 336 backreference expression. The special meaning of '&' and "\n" 337 in this context can be suppressed by preceding it by a backslash. 338<p> 339 A line can be split by substituting a newline ('\n') into it. 340 <p> 341 A substitution is considered to have been performed even if the 342 replacement string is identical to the string that it replaces.</td></tr> 343 * <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> 344 * <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> 345 * <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> 346 * <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> 347 * <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 348 corresponding characters in string2. If the number of characters in 349 the two strings are not equal, or if any of the characters in 350 string1 appear more than once, the results are undefined.</td></tr> 351 * </table> 352 */ 353 public static final SedOptionSets Options = SedOptionSets.INSTANCE; 354 355 /** 356 * Singleton {@link SedFactory factory} instance for the "sed" command. 357 */ 358 public static final SedFactory Factory = SedFactory.INSTANCE; 359 360 // no instances 361 private Sed() { 362 super(); 363 } 364}