JREPL Search Replace [/Option [Value]]...
JREPL /??|HELP]
Perform a global regular expression search and replace operation on
each line of ASCII input from stdin and prints the result to stdout.
Each parameter may be optionally enclosed by double quotes. The double
quotes are not considered part of the argument. The quotes are required
if the parameter contains a batch token delimiter like space, tab, comma,
semicolon. The quotes should also be used if the argument contains a
batch special character like &, |, etc. so that the special character
does not need to be escaped with ^.
Search - By default, this is a case sensitive JScript (ECMA) regular
expression expressed as a string.
JScript regex syntax documentation is available at
https://msdn.microsoft.com/en-us/library/ae5bf541.aspx
Replace - By default, this is the string to be used as a replacement for
each found search expression. Full support is provided for
substitution patterns available to the JScript replace method.
For example, $& represents the portion of the source that matched
the entire search pattern, $1 represents the first captured
submatch, $2 the second captured submatch, etc. A $ literal
can be escaped as $$.
An empty replacement string must be represented as "".
Replace substitution pattern syntax is fully documented at
https://msdn.microsoft.com/en-US/library/efy6s3e6.aspx
Binary input with NULL bytes requires either the /M option, or the file
must be read using ADO by appending the character set name to the file name.
For example, if your input is ASCII containing null bytes, then you must
use: /F "input.txt" /M or /F "input.txt|ascii".
The meaning of extended ASCII byte codes >= 128 (0x80) is dependent on the
active code page. Extended ASCII within arguments and variables may require
the /XFILE option.
Options: Behavior may be altered by appending one or more options.
The option names are case insensitive, and may appear in any order
after the Replace argument.
/A - Only write altered lines. Unaltered lines are discarded.
If the /S option is used, then write the result only if
there was a change anywhere in the string. The /A option
is incompatible with the /M option unless the /S option
is also present.
/APP - Modify /O behavior to Append results to the output file.
/B - The Search must match the Beginning of a line.
Mostly used with literal searches.
/C - Count the number of input lines and store the result in global
variable cnt. This value can be useful in JScript code associated
with any of the /Jxxx options.
This option is implicitly enabled if /INC or /EXC contains a
negative value.
This option is incompatible with the /M and /S options.
If the input data is piped or redirected, then the data is first
written to a temporary file, so processing does not start until
the end-of-file is reached.
/D Delimiter
Specifies the Delimiter string to use after line numbers and/or
byte offsets that are output due to the /N or /OFF options.
The default value is a colon. The delimiter may be set to an
empty string by using /D "".
/E - The Search must match the End of a line.
Mostly used with literal searches.
/EOL EndOfLineString
Write lines using EndOfLineString as the line terminator.
Standard JScript escape sequences may be used.
The default is "rn" (CarriageReturn LineFeed).
The value may be set to an empty string to eliminate linefeeds
from the output.
/EOL has no effect if the /M option is used unless /MATCH,
/JMATCH, or /JMATCHQ is also used.
Note that /EOL does not affect input.ReadLine or output.WriteLine
methods in user supplied JScript. ReadLine always accepts both
rn and n as line terminators. And WriteLine always terminates
lines with rn.
/EXC BlockList
Exclude (do not search/replace) lines that appear within at least
one block within BlockList. A block may be a single line, or a
contiguous range of lines between a start and end line. The /EXC
option is incompatible with /M and /S.
The syntax for specifying a BlockList is complex. Whitespace
should not appear anywhere except for possibly within a Regex or
String.
BlockList = {Block}[,{Block}]...
{Block} = {SingleLine}|{LineRange}
{SingleLine} = {LineSpec}[{Offset}]
{LineRange} = {LineSpec}[{Offset}]:{EndLineSpec}[{Offset}]
{LineSpec} = [-]LineNumber|{Regex}[/]|{String}[/]
{EndLineSpec} = [-]LineNumber|+Number|{Regex}|{String}
{Regex} = /Regex/[i|b|e]...
{String} = 'String'[i|b|e]...
{Offset} = +Number|-Number
A line may be identified by its LineNumber, or by a Regex that
matches the line, or a String literal that is found in the line.
Once identified, a line position may be adjusted forward or
backward via the optional Offset.
A negative LineNumber is counted from the end of the file.
So 1 is the first line of input, and -1 is the last line. The /C
option is automatically activated if any block identifies a line
via a negative line number.
A Block Regex uses mostly standard JScript syntax. Both a Regex
and a String may use any of the escape sequences defined by the
/XSEQ option, even if the /XSEQ option has not been set. Any /
literal within a Regex must be escaped as /. Any ' literal
within a String must be escaped as ''.
A Regex or String may be followed by any combination of the
following flags:
i - Ignore case
b - The search must match the beginning of a line
e - The search must match the end of a line
/EXC and /INC ignore the /I option.
A line or range start that is identified by a Regex or String may
match multiple lines within the input. Only the first matching
line is used if the Regex or String is terminated by an extra /.
A Line block or Range start that is identified by a Regex or
String cannot have a negative Offset.
If the end of a Range is specified as + followed by a Number,
then the Number is treated as an offset from the start of the
Range (after any start Offset has been applied).
If the end of a Range is specified as a Regex or String, then the
block end is the first line that matches after the beginning of
the block. The extra / cannot be used with an end of Range Regex
or String. The Offset must be greater than or equal to -1 if a
Regex or String is used. If the end of Range Regex or String is
not found, then the block continues to the end of file.
Examples:
/EXC "1:5,10,-5:-1"
Exclude the first 5, 10th, and last 5 lines.
/EXC "/^:/"
Exclude all lines that begin with a colon
/EXC "/^Begin$/+1:/^End$/-1"
Exclude all lines that are after a "Begin" line, and before
the next "End" line. Multiple blocks may be excluded.
/EXC "/^DATA/i/:+10"
Exclude the first line that begins with DATA, ignoring case,
and exclude the next 10 lines as well.
/EXC "'[START]':'[STOP]'"
Exclude lines beginning with a line that contains the literal
[START] and ending with the next line that contains [STOP].
/EXC "'[START]'be:'[STOP]'be"
Exclude lines beginning with a [START] line (exact match)
and ending with the next [STOP] line (exact match).
/F InFile[|CharSet[|NB]]
Input is read from file InFile instead of stdin.
If |CharSet (internet character set name) is appended to InFile,
then the file is opened via ADO using the specified CharSet value.
JREPL still recognizes both n and rn as input line terminators
when using ADO. Both ADO and the CharSet must be available on the
local system. Appending |NB to the |CharSet normally has no impact.
The |NB No BOM flag is only useful when combined with /O -.
Note: Input containing null bytes cannot be read unless ADO is
used, or else the /M option must be used.
/H - Highlight all replaced or matched text in the output using the
strings defined by /HON and /HOFF.
/HON and /HOFF default to ANSI escape sequences that swap the
foreground and background colors.
/HU may be a better option if the current COLOR does not match
the console default.
Native support for ANSI escape sequences requires Windows 10 or
higher. ANSI escape sequences only work on the Windows 10 console
if the "Use legacy console" option is off in console properties.
In addition, one of the following must be used:
- The /VT option can be used to enable the escape sequences for
a single JREPL run.
or
- The registry can have the following DWORD defined, which will
enable escape sequences for all console applications.
[HKEY_CURRENT_USERConsole]
"VirtualTerminalLevel"=dword:00000001
/HON HighlightStart
Defines the string to start highlighting text, normally an ANSI
escape sequence.
Default is x1B[7m - Swap foreground and background colors.
/HOFF HighlightEnd
Defines the string to end highlighting text, normally an ANSI
escape sequence.
Default is x1B[0m - Return to the console default format.
/HU - Underline all replaced or matched text in the output using ANSI
escape sequences.
This is the same as using /H with /HON=x1B[4m and /HOFF=x1B[24m
/I - Ignore case when searching.
/INC BlockList
Only Include (search/replace) lines that appear within at least
one block within BlockList. A block may be a single line, or a
contiguous range of lines between a start and end line. The /INC
option is incompatible with /M and /S.
A line within an /INC block is not included if it also appears
within an /EXC block.
See the /EXC help for the syntax of a BlockList.
Examples:
/INC "1:5,10,-5:-1"
Include the first 5, 10th, and last 5 lines.
/INC "/^:/"
Include all lines that begin with a colon
/INC "/^Begin$/+1:/^End$/-1"
Include all lines that are after a "Begin" line, and before
the next "End" line. Multiple blocks may be included.
/INC "/^DATA/i/:+10"
Include the first line that begins with DATA, ignoring case,
and include the next 10 lines as well.
/INC "'[START]':'[STOP]'"
Include lines starting with a line that contains the literal
"[START]" and ending with the next line that contains "[STOP]".
/INC "'[START]'be:'[STOP]'be"
Include lines beginning with a "[START]" line (exact match)
and ending with the next "[STOP]" line (exact match).
/J - A deprecated form of /JQ that is slow because the JScript code
is executed via the eval() function each and every match. This
form does not use $txt - The replace value is taken as the value
of the last JScript expression within Replace.
This option is only preserved so as not to break existing scripts.
/JBEG InitCode
JScript inititialization code to run prior to loading any input.
This is useful for initializing user defined variables for
accumulating information across matches. The default code is an
empty string.
/JBEGLN NewLineCode
JScript code to run at the beginning of each line, prior to
performing any search on the line. The line content may be
manipulated via the $txt variable. The default code is an empty
string. This option is incompatible with the /M and /S options.
/JEND FinalCode
JScript termination code to run when there is no more input to
read. This is useful for writing summarization results.
The default code is an empty string.
/JENDLN EndLineCode
JScript code to run at the end of each line, after all matches
on the line have been found, but before the result is printed.
The final result can be modified via the $txt variable. Setting
$txt to false discards the line without printing. The $txt value
is ignored if the /JMATCH option has been used. The default
code is an empty string. This option is incompatible with the
/M and /S options.
/JLIB FileList
Specifies one or more files that contain libraries of JScript
code to load before /JBEG is run. Multiple files are delimited
by forward slashes (/). Useful for declaring global variables
and functions in a way that is reusable.
/JMATCH - A deprecated form of /JMATCHQ that is slow because the JScript
code is executed via the eval() function each and every match.
This form does not use $txt - The replace value is taken as the
value of the last JScript expression within Replace.
This option is only preserved so as not to break existing scripts.
/JMATCHQ - Write each Replace value on a new line, discarding all text
that does not match the Search. The Replace argument is one or
more JScript statements with access to the same $ variables
available to the /JQ option. The code must store the final replace
value in variable $txt. A $txt value of false indicates the match
is to be ignored.
Note the trailing Q stands for Quick :-)
/JQ - The Replace argument is one or more JScript statements that
define the replacement value, and possibly do more. The code
must store the final replace value in variable $txt.
The following variables contain details about each match:
$0 is the substring that matched the Search
$1 through $n are the captured submatch strings
$off is the offset where the match occurred
$src is the original source string
Note the trailing Q stands for Quick :-)
/K PreContext:PostContext[:FILE]
/K Context[:FILE]
Keep matches - Search and write out lines that contain at least
one match, without doing any replacement. The Replace argument is
still required, but is ignored.
The integers PreContext and PostContext specify how many non-
matching lines to write before the match, and after the match,
respectively. If a single Context integer is given, then the same
number of non-matching lines are written before and after.
A Context of 0 writes only matching lines.
If :FILE is appended to the context, then the Search parameter
specifies a file containing one or more search terms, one term
per line. A line matches if any of the search terms are found
witin the line. The file can be opened via ADO if |CharSet
(internet character set name) is appended to the file name.
Note: the /V option does not apply to Search if /K :FILE is used.
/K is incompatible with /A, /J, /JQ, /JMATCH, /JMATCHQ, /M,
/MATCH, /R, /S, and /T.
/L - The Search is treated as a string literal instead of a
regular expression. Also, all $ found in the Replace string
are treated as $ literals.
/M - Multi-line mode. The entire input is read and processed in one
pass instead of line by line, thus enabling search for n. This
also enables preservation of the original line terminators.
The /M option is incompatible with the /A option unless the /S
option is also present.
Note: The /M option is one method to read binary data with null
bytes. The other option is to use ADO to read the file.
See the /F option for more info.
/MATCH - Search and write out each matching string on a new line,
discarding any non-matching text. The Replace argument is
ignored, but is still required.
/MATCH is incompatible with /A, /J, /JQ, /JMATCH, /JMATCHQ,
/K, /R and /T.
/N MinWidth
Precede each output line with the line number of the source line,
followed by a delimiter (colon by default). The default delimiter
can be overridden with the /D option.
Line 1 is the first line of the source.
The MinWidth value specifies the minimum number of digits to
display. The default value is 0, meaning do not display the
line number. A value of 1 displays the line numbers without any
zero padding.
The /N option is ignored if the /M or /S option is used.
/O OutFile[|CharSet[|NB]]
Output is written to file OutFile instead of stdout. Any existing
OutFile is overwritten unless the /APP option is also used.
If |CharSet (internet character set name) is appended to OutFile,
then the file is opened via ADO using the specified CharSet value.
The output line terminator still defaults to rn when using ADO,
and may be changed to n with the U option. Both ADO and the
CharSet must be available on the local system. Unicode files
written by ADO have a BOM by default. Appending |NB (or |anyvalue)
to the CharSet blocks the BOM from being written.
If /F InFile is also used, then an OutFile value of "-" overwrites
the original InFile with the output. A value of "-" preserves the
original input character set (and also any |NB No BOM indicator).
A value of "-|" explicitly transforms the file into the machine
default character set. A "-|CharSet[|NB]" value explicitly
transforms the file into the specified character set. The output
is first written to a temporary file with the same path and name,
with .new appended. Upon completion, the temp file is moved to
replace the InFile.
It is rarely useful, but /APP may be combined with /O -. But /APP
cannot be combined with /O "-|CharSet".
/OFF MinWidth
Ignored unless /JMATCHQ, /JMATCH, /MATCH, or /K is used.
Precede each line of output with the offset of the match within
the original source string, followed by a delimiter (colon by
default). The default delimiter can be overridden with the /D
option. The offset follows the line number if the /N option is
also used.
Offset 0 is the first character of the source string. The source
string is normally the current line. But if the /M option is used
then the source string is the entire file.
If used with /K, then the offset represents the first occurrence
of the search string within the line.
The MinWidth value specifies the minimum number of digits to
display. The default value is 0, meaning do not display the
offset. A value of 1 displays the offsets without any zero
padding.
/P FilterRegex
Only Search/Replace strings that match the Pre-filter regular
expression FilterRegex. All escape sequences defined by /XSEQ are
available to FilterRegex, even if /XSEQ has not been set.
FilterRegex is a global, case sensitive search by default.
The behavior may be changed via the /PFLAG option.
By default, /P passes the entire matched filter string to the
main Search/Replace routine. If your FilterRegex includes captured
groups, then you can add the /PREPL option to selectively pass one
or more captured groups instead.
The /P option ignores /I, but honors /M.
The /P option may be combined with /INC and/or /EXC, in which case
/P is applied after lines have been included and/or excluded.
Within the main Search argument, ^ matches the beginning of the
matched filter, and $ matches the end of the matched filter.
Example - Substitute X for each character within curly braces,
including the braces.
echo abc{xyz}def|jrepl . X /p "{.*?}"
result:
abcXXXXXdef
See /PREPL for an example showing how to preserve the enclosing
braces.
/PFLAG Flags
Set the search flags to be used when defining the /P FilterRegex.
Possible values are:
"g" - global, case sensitive (default)
"gi" - global, ignore case
"" - first match only, case sensitive
"i" - first match only, ignore case
If the search is not global, then the first match of each line
is used. If the /M option is used, then a non-global search uses
only the first match of the entire input.
Note that the /P FilterRegex multiline mode is contolled by the
/M option. The "m" flag cannot be used with /PFLAG.
/PREPL FilterReplaceCode
Specify a JScript expression FilterReplaceCode that controls
what portion of the /P Pre-filter match is passed on to the main
Search/Replace routine, and what portion is preserved as-is.
The expression is mostly standard JScript, and should evaluate to
a string value. $0 is the entire Pre-filter match, and $1 through
$N are the captured groups. The only non-standard syntax is the
use of curly braces to indicate what string expression gets passed
on to the main Search/Replace. Prior to executing the /P filter,
each brace expression within /PREPL is transformed as follows:
{Expression} --> (Expression).replace(Search,Replace)
Any JScript is allowed within /PREPL, except string literals
should not contain $, {, or }.
Using /P without /PREPL is the same as using /P with /PREPL "{$0}"
/PREPL cannot be used with /OFF.
Note that neither /V nor /XFILE apply to /PREPL.
Example - Substitute X for each character within curly braces,
excluding the braces.
echo abc{xyz}def|jrepl . X /p "({)(.*?)(})" /prepl "$1+{$2}+$3"
result:
abc{XXX}def
/R PreContext:PostContext[:FILE]
/R Context[:FILE]
Reject matches - Search and write out lines that do not contain
any matches, without doing any replacement. The Replace argument
is still required, but is ignored.
The integers PreContext and PostContext specify how many matching
lines to write before the non-match, and after the non-match,
respectively. If a single Context integer is given, then the same
number of matching lines are written before and after.
A Context of 0 writes only non-matching lines.
If :FILE is appended to the context, then the Search parameter
specifies a file containing one or more search terms, one term
per line. A line is rejected if any of the search terms are found
witin the line. The file can be opened via ADO if |CharSet
(internet character set name) is appended to the file name.
Note: the /V option does not apply to Search if /K :FILE is used.
/R is incomptaible with /A, /J, /JQ, /JMATCH, /JMATCHQ, /K, /M,
/MATCH, /S, and /T.
/RTN ReturnVar[:[-]LineNumber]
Write the result to variable ReturnVar.
If the optional LineNumber is present, then only that specified
line within the result set is returned. A LineNumber of 1 is the
first line. A negative LineNumber is measured from the end of the
result set, so -1 is the last line. /RTN always breaks lines at
rn and n - the /EOL value is ignored.
All byte codes except NULL (0x00) are preserved, regardless
whether delayed expansion is enabled or not. An error is thrown
and no value stored if the result contains NULL.
An error is thrown and no value stored if the value does not fit
within a variable. The maximum returned length varies depending
on the variable name and result content. The longest possible
returned length is 8179 bytes.
The line terminator of the last match is suppressed if /MATCH,
/JMATCH, or /JMATCHQ is used. There is also no line terminator
if LineNumber is specified.
/RTN uses a temporary output file to transfer the result to the
environment variable. By default the temporary file is written
as UTF-8. But the file is written using the CSCRIPT default code
page if the /XFILE option is used - the action may fail if the
result contains a character that cannot be mapped to the CSCRIPT
default code page.
/S VarName
The source is read from environment variable VarName instead
of from stdin. Without the /M option, ^ anchors the beginning
of the string, and $ the end of the string. With the /M option,
^ anchors the beginning of a line, and $ the end of a line.
The variable name must not begin with /.
/T DelimiterChar
/T FILE
The /T option is very similar to the Oracle Translate() function,
or the unix tr command, or the sed y command.
The Search represents a set of search expressions, and Replace
is a like sized set of replacement expressions. Expressions are
delimited by DelimiterChar (a single character). If DelimiterChar
is an empty string, then each character is treated as its own
expression. The /L option is implicitly set if DelimiterChar is
empty. Normally escape sequences are interpreted after the search
and replace strings are split into expressions. But if the
DelimiterChar is empty and /XSEQ is used, then escape sequences
are interpreted prior to the split at every character.
An alternate syntax is to specify the word FILE instead of a
DelimiterChar, in which case the Search and Replace parameters
specify files that contain the search and replace expressions,
one expression per line. Each file can be opened via ADO if
|CharSet (internet character set name) is appended to the file
name. Note that the /V option does not apply to Search and Replace
if /T FILE is used.
Each substring from the input that matches a particular search
expression is translated into the corresponding replacement
expression.
The search expressions may be regular expressions, possibly with
captured groups. Note that each expression is itself converted into
a captured group behind the scene, and the operation is performed
as a single search/replace upon execution. So backreferences within
each regex, and $n references within each replacement expression,
must be adjusted accordingly. The total number of expressions plus
captured groups must not exceed 99.
If an expression must include a delimiter, then an escape
sequence must be used (not an issue if the FILE syntax is used).
Search expressions are tested from left to right. The left most
matching expression takes precedence when there are multiple
matching expressions.
Examples using /T:
ROT13 - Simple character substitution is achieved by setting the
/T delimiter to an empty string. The search and replace strings
must have identical length. The use of line continuation aligns
the replace string directly below the search string, thus making
it very easy to see exactly how each character will be translated.
The "a" in the search string will be replaced by the "n" in the
replace string. And you can see the symmetry in that the "n" will
be replaced by "a".
echo The quick brown fox jumps over a lazy dog | jrepl^
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"^
"nopqrstuvwxyzabcdefghijklmNOPQRSTUVWXYZABCDEFGHIJKLM"^
/t ""
-- OUTPUT --
Gur dhvpx oebja sbk whzcf bire n ynml qbt
Simple string substitution - The /T option specifies that string
expressions are delimited by a space. The /L option prevents "."
from being interpreted as a regex wildcard character.
echo The blackbird flew through the blue sky. | jrepl^
"black blue sky ." "blue black night !" /l /t " "
-- OUTPUT--
The bluebird flew through the black night!
Simple string substitution using FILE - This is the same as the
prior example, except now the Search and Replace strings are in
the following files:
find.txt repl.txt
-------- --------
black blue
blue black
sky night
. !
The following command yields the same output as before:
echo The blackbird flew through the blue sky. | jrepl^
find.txt repl.txt /l /t file
Pig Latin - This example shows how /T can be used with regular
expressions, and it demonstrates how the numbering of captured
groups must be adjusted. The /T delimiter is set to a space.
The first regex is captured as $1, and it matches words that begin
with a consonant. The first captured group ($2) contains the initial
sequence of consonants, and the second captured group ($3) contains
the balance of the word. The corresponding replacement string moves
$2 after $3, with a "-" in between, and appends "ay".
The second regex matches any word, and it is captured as $4 because
the prior regex ended with group $3. Because the first regex matched
all words that begin with consonants, the only thing the second
regex can match is a word that begins with a vowel. The replacement
string simply adds "-yay" to the end of $4. Note that $0 could have
been used instead of $4, and it would yield the same result.
echo Can you speak Pig Latin? | jrepl^
"b((?:qu(?=[aeiou])|[bcdfghj-np-twxz])+)([a-z']+)b b[a-z']+b"^
"$3-$2ay $4-yay" /t " " /i
-- OUTPUT --
an-Cay you-yay eak-spay ig-Pay atin-Lay?
Pig-Latin with proper capitalization - This is simply an extension
of the prior example. The /JBEG option defines a fixCaps() function
that checks if the translated word is all lower case, except for one
capital letter after the "-". If so, then the initial letter is
capitalized, and the remainder is converted to lower caae. The /JQ
option treats the replacement strings as JScript expressions. The
first replacement expression uses fixCaps() to properly restore case.
echo Can you speak Pig Latin? | jrepl^
"b((?:qu(?=[aeiou])|[bcdfghj-np-twxz])+)([a-z']+)b b[a-z']+b"^
"$txt=fixCaps($3+'-'+$2+'ay') $txt=$4+'-yay'"^
/t " " /i /j /jbeg ^"^
function fixCaps(str){^
return str.search(/[a-z']+-A-Z*$/)==0 ?^
str.substr(0,1).toUpperCase()+str.substr(1).toLowerCase() : str^
}^"
-- OUTPUT --
An-cay you-yay eak-spay Ig-pay Atin-lay?
/TFLAG Flags
Used to specify XRegExp non-standard mode flags for use with /T.
/TFLAG is ignored unless both /T and /XREG are used.
/U - Write lines using a Unix line terminator n instead of Windows
terminator of rn. This is the same as using /EOL "n".
See /EOL help for more info.
/UTF - All input and output encodings are Unicode UTF-16 Little
Endian (UTF-16LE). This includes stdin and stdout. The only
exceptions are /JLIB and /XREG files, which are still read
as ASCII.
The xFFxFE BOM is optional for input.
Output files will automatically have the xFFxFE BOM inserted.
But stdout will not have the BOM.
Regular expression support of Unicode can be improved by using
the /XREG option.
Variables are never written to temporary files (/XFILE is ignored)
if /UTF is used.
Unfortunately, /UTF is incompatible with /RTN.
/V - Search, Replace, /INC BlockList, /EXC BlockList, /P FilterRegex,
/JBEG InitCode, /JBEGLN NewLineCode, /JEND FinalCode, and
/JENDLN EndLineCode all represent the names of environment
variables that contain the respective values. An undefined
variable is treated as an empty string.
Variable names beginning with / are reserved for option storage
and other internal uses. So user defined variables used with /V
must not have a name that begins with /.
/VT - Enables Virtual Terminal processing of ANSI escape sequences for
the current JREPL.bat process within the Windows 10 console. This
option is not needed if the registry has HKEY_CURRENT_USERConsole
"VirtualTerminalLevel" DWORD set to 1 in the registry.
/X - Shorthand for combined /XFILE and /XSEQ.
/XBYTES - Force creation of a new XBYTES.DAT file for use by the /XSEQ
option when decoding xnn sequences.
/XBYTESOFF - Force JREPL to use pre v7.4 behavior where /XSEQ xnn is
always interpreted as Windows-1252.
/XFILE - Preserves extended ASCII characters that may appear within
command line arguments and/or variables by first writing the
values to temporary files within the %TEMP% directory. Extended
ASCII values are byte codes >= 128 (0x80).
Temporary files may be needed when the cmd.exe active code page
does not match the default code page used by the CSCRIPT engine.
The default CSCRIPT code page is defined in the registry under
HKLMSYSTEMCurrentControlSetControlNlsCodePageACP.
The temporary files are written using the cmd.exe active code page.
The files are read using the CSCRIPT default code page. Extended
ASCII output to the console may appear wrong, but output written
to a file will be correct based on the cmd.exe active code page.
/XFILE is ignored (no temporary files written) if /UTF is used.
/XREG FileList
Adds support for XRegExp by loading the xregexp files specified
in FileList before any /JLIB code is loaded. Multiple files are
delimited by forward slashes (/). If FileList is simply a dot,
then substitute the value of environment variable XREGEXP for
the FileList.
The simplest option is to load "xregexp-all.js", but this
includes all available XRegExp options and addons, some of which
are unlikely to be useful to JREPL. Alternatively you can load
only the specific modules you need, but they must be loaded in the
correct order.
Once the XRegExp module(s) are loaded, all user supplied regular
expressions are created using the XRegExp constructor rather than
the standard RegExp constructor. Also, XRegExp.install('natives')
is executed so that many standard regular expression methods are
overridden by XRegExp methods.
/XREG requires XRegExp version 2.0.0 or 3.x.x. JREPL will not
support version 4.x.x (when it is released) because v4.x.x
is scheduled to drop support for XRegExp.install('natives').
One of the key features of XRegExp is that it extends the JScript
regular expression syntax to support named capture groups, as in
(?<name>anyCapturedExpression). Named backreference syntax in
regular expressions is k<name>. Named group syntax in Replace
strings is ${name}, and in Replace JScript code the syntax is
$0.name
The /T option is no longer limited to 99 capture groups when
/XREG is used. However, /T replace expressions must reference a
captured group by name if the capture index is 100 or above.
Every /T search expression is automatically given a capture group
name of Tn, where n is the 0 based index of the /T expression.
XRegExp also adds support for non-standard mode flags:
n - Explicit capture
s - Dot matches all
x - Free spacing and line comments
A - Astral
These flags can generally be applied by using (?flags) syntax
at the begining of any regex. This is true for /P, /INC, /EXC,
and most Find regular expressions. The one exception is /T doesn't
support (?flags) at the beginning of the Find string. The /TFLAG
option should be used to specify XRegExp flags for use with /T.
XRegExp also improves regular expression support for Unicode via
p{Category}, p{Script}, p{InBlock}, p{Property} escape
sequences, as well as the negated forms P{...} and p{^...}.
Note that example usage on xregexp.com shows use of doubled back
slashes like \p{...}. But JREPL automatically does the doubling
for you, so you should use p{...} instead.
See xregexp.com for more information about the capabilities of
XRegExp, and for links to download XRegExp.
/XSEQ - Enables extended escape sequences for both Search strings and
Replacement strings, with support for the following sequences:
\ - Backslash
b - Backspace
c - Caret (^)
f - Formfeed
n - Newline
q - Quote (")
r - Carriage Return
t - Horizontal Tab
v - Vertical Tab
xnn - Extended ASCII byte code expressed as 2 hex digits nn.
The code is mapped to the correct Unicode code point,
depending on the chosen character set. If used within
a Find string, then the input character set is used. If
within a Replacement string, then the output character
set is used. If the selected character set is invalid or
not a single byte character set, then xnn is treated as
a Unicode code point. Note that extended ASCII character
class ranges like [xnn-xnn] should not be used because
the intended range likely does not map to a contiguous
set of Unicode code points - use [x{nn-mm}] instead.
x{nn-mm} - A range of extended ASCII byte codes for use within
a regular expression character class expression. The
The min value nn and max value mm are expressed as hex
digits. The range is automatically expanded into the
full set of mapped Unicode code points. The character
set mapping rules are the same as for xnn.
x{nn,CharSet} - Same as xnn, except explicitly uses CharSet
character set mapping.
x{nn-mm,CharSet} - Same as x{nn-mm}, except explicitly uses
CharSet character set mapping.
unnnn - Unicode code point expressed as 4 hex digits nnnn.
u{N} - Any Unicode code point where N is 1 to 6 hex digits
JREPL automatically creates an XBYTES.DAT file containing all 256
possible byte codes. The XBYTES.DAT file is preferentially created
in "%ALLUSERSPROFILE%JREPL" if at all possible. Otherwise the
file is created in "%TEMP%JREPL" instead. JREPL uses the file
to establish the correct xnn byte code mapping for each character
set. Once created, successive runs reuse the same XBYTES.DAT file.
If the file gets corrupted, then use the /XBYTES option to force
creation of a new XBYTES.DAT file. If JREPL cannot create the file
for any reason, then JREPL silently defaults to using pre v7.4
behavior where /XSEQ xnn is interpreted as Windows-1252. Creation
of XBYTES.DAT requires either CERTUTIL.EXE or ADO. It is possible
that both may be missing from an XP machine.
Without the /XSEQ option, only standard JSCRIPT escape sequences
\, b, f, n, r, t, v, xnn, unnnn are available for the
search strings. And the xnn sequence represents a unicode
code point, not extended ASCII.
Extended escape sequences are supported even when the /L option
is used. Both Search and Replace support all of the extended
escape sequences if both the /XSEQ and /L options are combined.
Extended escape sequences are not applied to JScript code when
using any of the /Jxxx options. Use the decode() function if
extended escape sequences are needed within the code.
The following global JScript variables/objects/functions are available for
use in JScript code associated with the /Jxxx options. User code may safely
declare additional variables/objects/functions because all other internal
objects used by JREPL are hidden behind an opaque _g object.
ln - Within /JBEGLN, /JENDLN, and Replace code = current line number
Within /JBEG code = 0
Within /JEND code = total number of lines read.
This value is always 0 if the /M or /S option is used.
cnt - The total number of lines in the input. The value is undefined
unless the /C option is used.
skip - If true, do not search/replace any more lines until the value
becomes false. /JBEGLN and /JENDLN code are still executed for
each line, regardless. If set to true while in the midst of
searching a line, then that search will continue to the end of
the current line.
The default value is false.
This variable has no impact if the /M or /S options is used.
Note that this variable operates independently of the /INC
and /EXC options.
quit - If true, then do not read any more lines of input. The current
line is still processed to completion, and /JEND code is still
executed afterward.
The default value is false.
This variable has no impact if the /M or /S options is used.
env('varName')
Access to environment variable named varName.
decode( String [,CharSet] )
Decodes extended escape sequences within String as defined by
the /XSEQ option, and returns the result. CharSet specifies the
single byte character set to use for xnn escape sequences.
If CharSet is 'input', then the character set of the input is
used. If CharSet is 'output', then the character set of the
output is used. If CharSet is 'default' or undefined, then the
default character set for the machine is used. Otherwise,
CharSet should be a valid internet character set name understood
by the machine. If the selected character set is invalid or not
a single byte character set, then xnn is treated as a Unicode
code point.
All backslashes within String must be escaped an extra time to
use this function in your code.
Examples:
quote literal: decode('\q','output')
extended ASCII(128): decode('\x80','output')
backslash literal: decode('\\','output')
This function is only needed if you use any q, c, or u{N}
escape sequences, or xnn escape sequence for extended ASCII.
lpad( value, padString )
lpad( value, length [,padString] )
Used to left pad a value to a minimum width string. If the
value already has string width >= the desired length, then no
change is made. Otherwise it left pads the value with the
characters of the pad string to the desired length. If only
padString is specified, then the value is padded to the length
of padString. If length is specified with a padString, then
padString is replicated as needed to get the desired length.
If length is specified without padString, then spaces are used
for the padString.
Examples:
lpad(15,' ') returns ' 15'
lpad(15,4) returns ' 15'
lpad(15,'0000') returns '0015'
lpad(15,4,'0') returns '0015'
lpad(19011,4,'0') returns '19011'
lpad('A','. . . . .') returns '. . . . .A'
lpad('A',9,'. ') returns '. . . . .A'
lpad('AB','. . . . .') returns '. . . . AB'
lpad('AB',9,'. ') returns '. . . . AB'
rpad( value, padString )
rpad( value, length [,padString] )
Used to right pad a value to a minimum width string. If the
value already has string width >= the desired length, then no
change is made. Otherwise it right pads the value with the
characters of the pad string to the desired length. If only
padString is specified, then the value is padded to the length
of padString. If length is specified with a padString, then
padString is replicated as needed to get the desired length.
If length is specified without padString, then spaces are used
for the padString.
Examples:
rpad('hello',' ') returns 'hello '
rpad('hello',10) returns 'hello '
rpad('hello',' . . . . .') returns 'hello. . .'
rpad('hello',10,' .') returns 'hello. . .'
rpad('hell',' . . . . .') returns 'hell . . .'
rpad('hell',10,' .') returns 'hell . . .'
rpad('hello',2) returns 'hello'
inc( [blockNum] )
A boolean function that returns true or false.
Returns true if the current line appears within the specified
/INC blockNum. A blockNum of 0 specifies the first /INC block.
If blockNum is not specified, then returns true if the current
line appears within any /INC block.
exc( [blockNum] )
A boolean function that returns true or false.
Returns true if the current line appears within the specified
/EXC blockNum. A blockNum of 0 specifies the first /EXC block.
If blockNum is not specified, then returns true if the current
line appears within any /EXC block.
fso - An instantiation of the FileSystemObject object.
input - The TextStream object from which input is read.
This may be stdin or a file.
If the file was opened by ADO with |CharSet, then input is
an object that partially emulates a TextStream object, with
a private ADO Stream doing the actual work. The following
public members are available to the ADO object:
Property Method
------------- ----------
AtEndOfStream Read
ReadLine (line terminator n or rn)
SkipLine (line terminator n or rn)
Write
WriteLine (line terminator always rn)
Close
output - The TextStream object to which the output is written.
This may be stdout or a file. If /RTN is used, then the output
is first written to a temporary file before it is read and
stored in the return variable.
If the file was opened by ADO with |CharSet, then output is
an object that partially emulates a TextStream object (see the
input object).
stdin - Equivalent to WScript.StdIn
stdout - Equivalent to WScript.StdOut
stderr - Equivalent to WScript.StdErr
openOutput( fileName[|CharSet[|NB]] [,appendBoolean [,utfBoolean]] )
Open a new TextStream object for writing and assign it to the
output variable. If appendBoolean is truthy, then open the file
for appending.
If |CharSet is appended to the fileName, then open the file
using ADO and the specified internet character set name. The
output variable will be set to an object that partially
emulates a TextStream object (see the input object). Unicode
written by ADO will have a BOM by default. The BOM is blocked
by appending |NB (or |anyValue) to the CharSet.
If utfBoolean is truthy, then output is encoded as unicode
(UTF-16LE). The unicode file will automatically have the BOM
unless opened for appending. The utfBoolean argument is ignored
if |CharSet is also specified.
If fileName is falsey, then output is written to stdout.
All subsequent output will be written to the new destination.
Any prior output file is automatically closed.
eol - The line terminator used when writing output lines. This is the
same value set by the /EOL option.
See the /JQ option help for info about local $ variables that may be used
within replacement code when using /JQ or /JMATCHQ.
Help is available by supplying a single argument beginning with /? or /??:
/? - Writes all available help to stdout.
/?? - Same as /? except uses MORE for pagination.
/?Topic - Writes help about the specified topic to stdout.
Valid topics are:
INTRO - Basic syntax and default behavior
OPTIONS - Brief summary of all options
JSCRIPT - JREPL objects available to user JScript
RETURN - All possible return codes
VERSION - Display the version of JREPL.BAT
HISTORY - A summary of all releases
HELP - Lists all methods of getting help
Example: List a summary of all available options
jrepl /?options
/?WebTopic - Opens up a web page within your browser about a topic.
Valid web topics are:
REGEX - Microsoft regular expression documentation
REPLACE - Microsoft Replace method documentation
UPDATE - DosTips release page for JREPL.BAT
CHARSET - List of possible character set names for ADO I/O
Some character sets may not be installed
XREGEXP - xRegExp.com home page (extended regex docs)
/?/Option - Writes detailed help about the specified /Option to stdout.
Example: Display paged help about the /T option
jrepl /??/t
/?CHARSET/[Query] - List all character set names for use with ADO I/O
that are installed on this computer. Optionally restrict
the list to names that contain Query. Wildcards * and ? may
be used within Query. The default Query is an empty string,
meaning list all available character sets. The list is
generated via reg.exe.
Examples:
jrepl /??charset/ - Paged list of all available names
jrepl /?charset/utf - List of names containing "utf"
Possible ERRORLEVEL Return Codes:
If /? was used, and no other argument
0 = Only possible return
If /MATCH, /JMATCH, /JMATCHQ, /K, and /R were not used
0 = At least one change was made
1 = No change was made
2 = Invalid call syntax or incompatible options
3 = JScript runtime error
If /MATCH, /JMATCH, /JMATCHQ, /K, or /R was used
0 = At least one line was written
1 = No line was written
2 = Invalid call syntax or incompatible options
3 = JScript runtime error
JREPL.BAT version 8.5 was written by Dave Benham, and originally posted at
http://www.dostips.com/forum/viewtopic.php?f=3&t=6044