Command
	win

Purpose
	Editor - Word inserter

Aliases
	wordinserter, wordins, win

Syntax
	win [ <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.

	-c	Case insensitive. Case will be ignored when considering separator characters.

	-e	Consider empty words.

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 word.

		"5"	Target instance is only the fifth word.
		"5["	Target instance is everything after but excluding the fifth word.
		"5]"	Target instance is everything upto and including the fifth word.
		"[5"	Target instance is everything beginning with and including the fifth word.
		"[5["	This combination is INVALID.
		"[5]"	Target instance is only the fifth word. This is same as "5".
		"]5"	Target instance is everything upto but excluding the fifth word.
		"]5["	Target instance is everything outside but excluding the fifth word.
		"]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 following system variable plays an important role.

	$wsep	Word separator

	This variable is used to identify, number, and extract distinct words.
	See the 'systemvar' help topic for its description.
	You can change its value to highly refine your search procedure.
	We highly recommend that, if you change any system variable's value, you restore it
	after the search is complete, as many system variables are often
	used by more than one command.

	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
	Assume that we have a database table which we have imported to file oldtable.txt. This
	file contains one row per line, and columns are separated by tabs. We want to insert
	a str column (default value "") before column 3, and a real column (default value 0.0)
	before column 5. The following code will do that.

	# Save the old value of word separator.
	var str saved_wsep
	set $saved_wsep = $wsep

	# Set word separator to tab only. Its default value contains space and other
	# characters as well and some of our columns may contain spaces.
	set $wsep = "\t"

	# Get the entire table in a str variable.
	var str old_table
	repro "oldtable.txt" >$old_table

	# We will collect the new table in the following variable row by row.
	var str new_table

	# We will use the following to determine if we want to write a new line.
	# We write a newline before each row, but only if it is not the first row.
	var bool first_row
	set $first_row = true

	# Process one row at a time until $table has nothing in it.
	while ($old_table <> "")
	do

	  # Get one row at a time into a str variable.
	  # Note that some rows can be empty (but still will have the separating tabs).
	  var str row
	  lex -e "1" $old_table > $row

	  # We will process column 5 first. That way, all columns 1-4 will remain unchanged.
	  # We will process column 3 next.
	  win -e "5" "0.0\t" $row > null
	  win -e "3" "\t" $row > null

	  # We are using -e in the above win commands because we want to consider the
	  # possibility that some of the columns may be empty.

	  # We are using > null in the above win commands because we don't want to see
	  # the large output that may result, We only want to change $row.
	  # Plus the intermediate output may be confusing.
	  # If you want to see the correct resulting rows one by one on the screen, add the
	  # following.
	  # echo $row

	  # Add this row to new table.
	  # We will add a newline before $row, but only if this is not the first row.
	  if ($first_row)
	  do
	    set $new_table = $new_table + $row
	    set $first_row = false	# Going forward we are NOT on the first row.
	    done
	  else
	    set $new_table = $new_table + "\n" + $row
	  endif

	done
	
	# All rows are processed, the new table is available in $new_table. Write it
	# to a file "newtable.txt" so it can be exported back to the database.
	echo $new_table > "newtable.txt"

	# Restore the previous value of word separator.
	set $wsep = $saved_wsep

Invalid Examples

	var int i
	...
	win "5" "This is the fifth word:" $i

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

See Also
systemvar
var
echo
escape
wen
wex
wap
wal
sin
lin
chin