Command
	chex

Purpose
	Editor - Character extractor

Aliases
	characterextractor, charext, chex

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

Options
	-p	Preserve the input string. Without this option, when
		a part of the input string is extracted (called the extraction target,
		or just target), that part is removed from
		the input string. (This is done so that each subsequent
		extract command will produce subsequent targets.)
		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_limiter> appears before the <n>. The <end_limiter>
		appears after the <n>.

		We will now explain the role of these bounders with an example. Assume that
		we are looking for the fifth character.
		We will show all the nine combinations of bounders.

		"5"	Extract only the fifth character.
		"5["	Extract everything after but excluding the fifth character.
		"5]"	Extract everything upto and including the fifth character.
		"[5"	Extract everything beginning with and including the fifth character.
		"[5["	This combination is INVALID.
		"[5]"	Extract only the fifth character. This is the same as "5".
		"]5"	Extract everything upto but excluding the fifth character.
		"]5["	Extract everything outside but excluding the fifth character.
		"]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 character(s) from the input string and writes them to
	the stream output. 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 extracted part 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. Use the command on that
	str variable. Then write the str variable back to the input file.

	Variables, expressions and inline commands can be used very effectively with
	all extractor (stex, lex, wex, chex) commands. As an explaratory
	(but practically not very useful) example, consider the following.

	var str s
	set $s="abcdefghijklmnopqrstuvwxyz"
	var int i
	set $i=1
	while ($i <= 26)
	do
	    chex -p { echo $i"]" } $s
	    set $i = $i + 1
	done

	The above code will successively extract and show continuous alphabetic strings
	of incresing size, such as a, ab, abc, abcd and so on. (The ] bounder is used merely
	to explain the use of inline command.) If the chex command is entered as

	chex -p $i] $s

	it will produce erroneous output. The inline echo command is very helpful in
	correctly supplying the <n>, <start_bounder> and <end_bounder> to the chex command.

		
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 characters in a word. Assume the original word
	to be reversed in a str variable $word. We will construct the reversed word in
	str variable $reversedWord.

	var str word
	var str reversedWord

	while ($word <> "")
	  set $reversedWord = $reversedWord + { chex "l" $word }	# "l" for Last character.

	echo "Reversed word=\t" $reversedWord


Invalid Examples

	chex 1[ $s	# Extract every thing after first character.
	Will produce an error. 1[ must be enclosed in double quotes as "1[".

See Also
systemvar
var
echo
chen
chin
chap
chal
stex
lex
wex