Command
	lex

Purpose
	Editor - Line extractor

Aliases
	lineextractor, linext, lex

Syntax
	lex [ <options> ] " [<start_bounder>] <n> [<end_bounder>] " <input_string>

Options
	-p	Preserve the input string. Without this option, when
		a part of the input string (called the extraction target,
		or just target) is extracted, that part is removed from
		the input string. (This is done so that each subsequent
		extract command will produce subsequent lines.) With this
		option, the input string is left unchanged.

	-e	Count and return empty strings. This option is useful, for example, if you
		have records separated by newlines in a file, and you want to receive empty records.

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


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"	Extract only the fifth line.
		"5["	Extract everything after but excluding the fifth line.
		"5]"	Extract everything upto and including the fifth line.
		"[5"	Extract everything beginning with and including the fifth line.
		"[5["	This combination is INVALID.
		"[5]"	Extract only the fifth line. This is same as "5".
		"]5"	Extract everything upto but excluding the fifth line.
		"]5["	Extract everything outside but excluding the fifth line.
		"]5]"	This combination is INVALID.

	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 extracted content is added to stream output.

Stream Error
	Any errors are listed here.

Description
	The command extracts the target line(s) from the input string and writes them to
	the stream output or redirected output target. If <input_string> is a constant or an expression,
	it remains unchanged. If <input_string> is a variable, and if the -p option is not
	specified, the target is removed from the <input_string>. Similarly, if <input_string>
	is a variable, and if the -p option is specified, the <input_string> remains unchanged. 

	The command CAN ALSO BE USED WITH FILES. Simply read in the contents
	of the file using the repro command into a str variable. The following is
	an example. Assume that we want to operate the lex command on file "My Code.java".

	var str s
	repro "My Code.java" > $s
	# Do something with $s using the lex command.
	# Then write the input string back to the file.
	echo $s > "My Code.aspx"

	The following system variable plays an important role.

	$lsep	Line separator

	Each character in $lsep is considered to be a 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. This restoration can be done using code
	similar to the following.


	# Save the original $lsep.

	var str saved_lsep
	set $saved_lsep = $lsep

	...

	# Restore the original value of $lsep.
	set $lsep = $saved_lsep

	# Good job !

		
Restrictions
	If the <input_string> is specified as a constant or as a str expression,
	the presence or absence of option -p is ignored. A constant never changes its value.

Valid Examples

	The following example reverses lines in a file. Assume the file name is in
	$fileName.

	var str $fileName
	# Assign value of $fileName

	var str content
	var str line
	repro $fileName > $content

	while ($content <> "")
	do
	  # Extract the last line. Allow empty.
	  lex -e "l" $content > $line	# Note we are using Ell (l) for last line.
	  echo $line
	  done

Invalid Examples
	var str s
	# Assign value to $s
	lex 1[ $s	# Extract every thing after first line.
	Will produce erroneous output. 1[ must be enclosed in double quotes as "1[". It can however be
	also passed as a variable. The following code shows that.

	Let's say you don't know the line number you want to extract up-front. You have it
	available only in a variable $num.

	var str s
	var int num
	# Value of num and s are set.
	# We will create a variable for passing as argument to the lex command.
	var str lex_arg
	set $lex_arg = makestr(int($num))	# We are converting $num to str.
	set $lex_arg = $lex_arg+"["		# Should result in "1[", "5[", etc.
	lex $lex_arg $s		# Will correctly extract parts of s after (and excluding) line number $num.

See Also
systemvar
var
echo
len
lin
lap
lal
stex
wex
chex