Command
	sin

Purpose
	Editor - String inserter

Aliases
	stringinserter, strins, sin

Syntax
	sin [ <options> ] " [<start_bounder>] ^ <search_string> ^ [<n>] [<end_bounder>] " <insert_string> <input_string>

Options
	-p	Preserve the input string. Without this option, the <insert_string>
		is inserted into <input_string>. With this
		option, the <input_string> is left unchanged.

	-c	Case insensitive. Case will be ignored when searching for the
		<search_string> in <input_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 returned - "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
		will 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 "email:".

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

		In all VALID cases, the <insert_string> is inserted BEFORE the target instance.

	<insert_string>
		The string to insert before the target instance.
		

Stream Input	
	Stream input is ignored.

Stream Output
	The original input along with inserted content is added to stream output.

Stream Error
	Any errors are listed here.

Description
	The command inserts the <insert_string> before 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

		
Restrictions


Valid Examples
	var str s
	set $s = "Home: 123 East Main Street"
	sin "^Home^" "My " $s
	The above will insert "My " before the first instance of "Home" in string $s.
	It will also print the resulting string to stream output. To change the variable $s
	only, and not to see the output, use the following.

	sin "^Home^" "My " $s > null

	If you want to see the output but leave the variable $s unchanged, use the -p option, as follows.

	sin -p "^Home^" "My " $s

	sin "^Home^5" "My " $s
	The above will insert "My " before the fifth instance of "Home" in string $s. If the fifth
	instance does not exist, no changes will be made.

	sin "^Home^5]" "My " $s
	The ] suggests that the target string is everything upto and including the fifth instance
	of "Home". Thus, if the fifth instance of "Home" exists, "My " will be inserted before the whole
	string (and not before the fifth instance). If the fifth instance of "Home " does not exist, no
	changes will be made.

Invalid Examples
	var int i
	...
	sin "^Zip Code^" "Postal Code or " $i

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

See Also
systemvar
var
echo
escape
sen
stex
sap
sal
lin
win
chin
RE