Command
	chin

Purpose
	Editor - Character inserter

Aliases
	characterinserter, charins, chin

Syntax
	chin [ <options> ] " [<start_bounder>] <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.

	-n	Consider non-printable characters. This option is useful if you
		wish to see formating and other special characters within a string.


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. 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. <n> must be either
		a number higher than 0 or the letter l (which indicates the last instance).


	<start_bounder>
	<end_bounder>
		This argument can either be absent, the character [ or the character ].
		The <start_bounder> appears before the <n>. The <end_bounder>
		appears after the <n>.

		We will now explain the role of these bounders with an example.
		We will assume that we are looking for fifth character.

		"5"	Target instance is only the fifth character.
		"5["	Target instance is everything after but excluding the fifth character.
		"5]"	Target instance is everything upto and including the fifth character.
		"[5"	Target instance is everything beginning with and including the fifth character.
		"[5["	This combination is INVALID.
		"[5]"	Target instance is only the fifth character. This is same as "5".
		"]5"	Target instance is everything upto but excluding the fifth lcharacter.
		"]5["	Target instance is everything outside but excluding the fifth character.
		"]5]"	This combination is INVALID.

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

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

	<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 "mypage.html" > $content
	# Perform the desired 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 { echo $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
	None.

Valid Examples
	See above

Invalid Examples

	var int i
	...
	chin "1" "This is the first character: " $i

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

See Also
systemvar
var
echo
escape
chen
chex
chap
chal
sin
lin
win