Command
	lin

Purpose
	Editor - Line inserter

Aliases
	lineinserter, lineins, lin

Syntax
	lin [ <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 lines.

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 (line 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 line.

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

	$lsep	Line separator

	This variable is used to identify, number, and extract distinct lines.
	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.
		
Restrictions
	None.

Valid Examples
	This example will read a C Plus Plus code file in sample.cpp, and produce an output
	where all lines (including empty lines) are numbered. Each line will be printed with
	line number, followed by tab, followed by the line itself.

	# Read contents of file into a str.
	var str content
	repro "Sample.cpp" > $content

	# Get the total number of lines.
	var int total_num
	set $total_num = { len -e $content }	# Note that we used -e for empty lines.

	# Print lines one by one.
	var int num	# We will track the gradually increasing line number here.
			# $num currently has the default value of 0.
	while ($num < $total_num)
	do
	  # Increment $num
	  set $num = $num+1

	  # We will create a dynamic argument that passes <n> to the lin command.
	  # (We will not be using start or end bounders in this example, just <n>.
	  var str n
	  set $n=makestr(int($num))	# Should result in "1", "2", etc.

	  # We will create another dynamic argument that passes the <insert_string> to the lin command.
	  var str insert_string
	  set $insert_string = makestr(int($num))	# We created a str version of $num
	  set $insert_string = $insert_string + "\t"	# Should result in 1\t, 2\t, etc.

	  # Insert $insert_string into the n'th line.
	  lin -e $n $insert_string $content >null
	  done

	# Output the resulting $content. It now has line numbers.
	echo $content

Invalid Examples

	var int i
	...
	lin "l" "This is the last line: " $i

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

See Also
systemvar
var
echo
escape
len
lex
lap
lal
sin
win
chin