Command
	sal

Purpose
	Editor - String alterer

Aliases
	stringalter, stralt, sal

Syntax
	sal [ <options> ] " [<start_bounder>] ^ <search_string> ^ [<n>] [<end_bounder>] " <alter_string> <input_string>

Options
	-p	Preserve the input string. Without this option, the <input_string> itself
		is altered and the altered string is returned in stream output. With this
		option, the <input_string> is left unchanged and the altered string is
		returned in stream output.

	-c	Case insensitive. Case will be ignored when searching for the
		<search_string>. This option is very useful
		when parsing links, emails, tags and commands in web pages.
		For example, with this option, if the search string is "href=",
		all the following  string instances will be processed - "HREF=",
		"HRef=", "href=". Without this option, case is considered
		during the string search. In either case, the resulting string
		and <input_string> are returned in their original case.

	-r	<search_string> is a regular expression. See help page on RE
		for syntax of regular expressions.


Arguments
	<input_string>
		The input string on which this command will operate. It
		can be specified as a str constant or str variable or an
		expression resulting in a str value.

		If a str constant is used, we highly recommend using
		double quotes around it, such as "John Doe".
		Without the double quotes, the spaces in the input string
		may produce errors or erroneous output. In case of a str constant or a str
		expression, the -p option is assumed.

	<n>	The instance number. The input string will be searched for this
		instance of the target. Instances are counted from 1. If <n> is
		not specified, the first instance will be returned. If specified,
		<n> must be either a number higher than 0 or the letter l (which indicates
		the last instance).

	<search_string>
		The string to search for. The input string will be searched for
		this search string.

		The <search_string> needs to be enclosed in carets (^). The symbol
		is also known as the "Cut-here" symbol.

		If the <serach_string> itself contains a caret (^), an opening square bracket ([),
		a closing square bracket (]) or a double quote ("), escape them with a backslash,
		as \^, \[, \] and \". See help page on escape for more details.

		If the -r option is specified, the <search_string> is assumed to be a regular
		expression.

	<start_bounder>
	<end_bounder>
		This argument can either be absent, the character [ or the character ].
		The <start_bounder> appears before the first cut-here or caret (^).
		The <end_bounder> appears after the <n>.

		We will now explain the role of these bounders with an example.
		We will assume that the target string is "href=".

		"^href=^5"	Target instance to operate on is only the fifth instance of string "href=".
		"^href=^5["	Target instance to operate on is everything after but excluding the fifth instance of string "href=".
		"^href=^5]"	Target instance to operate on is everything upto and including the fifth instance of string "href=".
		"[^href=^5"	Target instance to operate on is everything beginning with and including the fifth instance of string "href=".
		"[^href=^5["	This combination is INVALID.
		"[^href=^5]"	Target instance to operate on is only the fifth instance of string "email:". This is same as "^href=^5".
		"]^href=^5"	Target instance to operate on is everything upto but excluding the fifth instance of string "href=".
		"]^href=^5["	This combination is INVALID.
		"]^href=^5]"	This combination is INVALID.

		In all VALID cases, the <alter_string> is substituted (altered) IN PLACE OF
		the target instance.


	<alter_string>
		The target instance is replaced (altered) with this string.

	The quotes in the command syntax are required. Without the double quotes, an error
	or erroneous output may be produced.
		

Stream Input	
	Stream input is ignored.

Stream Output
	The altered <input_string> is added to stream output.

Stream Error
	Any errors are listed here.

Description
	The command substitutes (alters) the <alter_string> IN PLACE OF the target instance.

	The command CAN ALSO BE USED WITH FILES. Simply read in the contents
	of the file using the repro command into a str variable. Perform any
	desired operations on the str variable, then write the str variable
	back to the file. The following is an example.

	var str content
	# Read file.
	repro myfile.html > $content
	# Perform the desire operations on $content.
	.
	.
	.
	# Write the resulting str variable back to file.
	echo $content >myfile.html

	This can also work on a collections of files, from which we want
	to operate on one file at a time. Let's say that we have a list of
	files in a str variable $fileList. The following is an example of
	how to do this.

	var str fileList
	# Collect the list of file in $fileList.
	.
	.
	.
	# Operate on files one by one.
	var str file
	# Get the first file.
	lex "1" $fileList > $file
	while ($file <> "")
	do
	  # Operate on this file.
	  var str content

	  # Read file.
	  repro $file  > $content

	  # Operate on file content.
	  .
	  .
	  .

	  # Write the resulting content back to file.
	  echo $content > { echo $file }

	  # Get the next file.
	  lex "1" $fileList > $file
	  done
	  
	
	Note that the output of the echo $content command is redirected to { echo $file }
	which will actually write the output to the file. If we had redirected the output
	of the echo $content command to just $file, that would have written the output
	to the variable $file itself, and not to the actual file whose name is in
	$file.
		
Restrictions


Valid Examples
	var str s
	...
	sal "^Zip Code^" "Postal Code" $s

	Will change the first instance of "Zip Code" to "Postal Code".
	Similarly, it will change the first instance of "Zip Code:" to "Postal Code:".

Invalid Examples

	var int i
	...
	sal "^Zip Code^" "Postal Code" $i

	Will produce error. Variable $i is not a str variable.

See Also
systemvar
var
echo
escape
sen
stex
sin
sap
lal
wal
chal
RE