$EPIC: expansions,v 1.1 2003/05/29 23:09:03 jnelson Exp $

		$-expansion and Quoting Hell

Whenever you give epic a string of text, epic will usually run it through 
the "expander" before it uses it.  The expander has four main jobs:

	1) Substitute $-expandos with whatever they evaluate to
	2) Remove any \c sequences (c is any character) (**** SEE BELOW ****)
	3) Find the start of the "next" command in a command set.
	4) Determine if a numeric expando is used in the text.

The following places use the expander:

* alias.c		prepare_alias_call
	* To expand "default" values in argument list, eg
		/alias oof (var1 default "$ooga") {...}

* commands.c		parse_line		(**** SEE BELOW ****)
	* To extract and expand the first command from a block of commands
	  prior to execution; to determine if the command uses a numeric
	  expando and to append $* if it does not, eg
		/alias oof {echo $ooga;echo hi}
		/alias booya msg

* expr.c		next_unit	(SETUP_IMPLIED)
	* To expand the variable name on the left hand side of an 
	  implied assignment, eg
		@ $ooga += 3

* expr.c		next_unit	([...] handling)
	* To expand the inside of [...] operator in an expression which 
	  starts with $ but is not a numeric expando, eg
		@ var = [$ooga]

* expr.c		next_unit	([...] handling)
	* To expand the inside of [...] operator that contains a $ or \
	  character, eg
		@ var = [one two $ooga my shoe]
		@ var = [one two \three four]

* expr.c		next_unit	(pre/post in/decrement operator)
	* To expand the variable name operand of the pre or post increment
	  or decrement operators, eg
		@ $ooga++
		@ --$ooga

* expr.c		next_unit	(= operator handling)
	* To expand the variable name on the left hand side of a straight
	  assignment, eg
		@ $ooga = 3

* expr.c		alias_special_char
	* To expand the inside of the width qualifier following a $, eg
		$[$ooga]var1

* expr.c		alias_special_char
	* To expand the inside of $(...) (``indirect'') expando, eg
		$($ooga)

* expr2.c		get_raw_token		(NEW MATH PARSER)
	* To convert an operand that is available as an "LVAL" when it is
	  needed to be used in a "RAW" context, eg
		@ var1 = $ooga

* expr2.c		get_token_expanded	(NEW MATH PARSER)
	* To convert an operand that is available as a "RAW" value when it
	  is needed to be used in an "EXPANDED" context, eg
		@ var1 = [$ooga]

* functions.c		call_function
	* To expand the argument list contained within parenthesis to a 
	  function being called, eg
		@ func($ooga)

* functions.c		function_cparse		($cparse())
	* To expand the resulting string after the cparse substitutions, 
	  for BitchX compatability, eg
		/echo $cparse("one two" buckle my $1 shoes $ooga)

* hook.c		do_hook
	* To expand the inside of a flexible hook before pattern matching, eg
		/on msg '$ooga *' {...}

* if.c			fe
	* To expand the word list argument to the /FE command, eg
		/fe ($ooga) {...}

* if.c			for_fe_cmd
	* To expand the word list argument to the /FOR I IN (...) command, eg
		/for i in ($ooga) {...}

* if.c			switchcmd
	* To expand the control string argument to the /SWITCH command, eg
		/switch ($ooga) {....}

* if.c			switcmd
	* To expand the matching string argument to the /SWITCH command, eg
		/switch ($*) {($ooga) {...}}

* if.c			repeatcmd
	* To expand the number-iterations argument to the /REPEAT command, eg
		/repeat $ooga ....

* input.c		update_input
	* To expand the value of /set input_prompt prior to display, eg
		/set input_prompt ${ooga}>

* ircaux.c		remove_brackets
	* To expand the inside of a variable array qualifier, eg
		$var1[$ooga]

* log.c			add_to_log
	* To rewrite text sent to a log before writing it, eg
		/set log_rewrite $ooga $1-
		/log new rewrite "$ooga $1-"

* numbers.c		banner
	* To expand /set banner prior to display when /set banner_expand on, eg
		/set banner $ooga
		/set banner_expand on

* output.c		vsay
	* To expand /set banner prior to display when /set banner_expand on, eg
		/set banner $ooga
		/set banner_expand on

* queue.c		queuecmd
	* To expand the command bodies at registration time if -expand_now
	  is used, eg
		/queue -expand_now {$ooga}

* screen.c		add_to_window
	* To rewrite text sent to a window before displaying it, eg
		/set output_rewrite $ooga $1-

* status.c		make_status
	* To expand the status bar after substitution but before displaying 
	  it when /set status_does_expandos on, eg
		/set status_user1 $ooga
		/set status_does_expandos on

==============================================================================
The "dequoter" is the function that removes \'s from a text string.  It is the
place that most commonly causes ``quoting hell''.  Each time a function is 
passed through the "dequoter", another level of \'s are removed.

The "dequoter" is malloc_strcat_ues_c, and it is called by the following:

* expr.c		expand_alias
	* To copy portions of the original string that are not part of 
	  a $-expando, contained withing parenthesis, or braces, 

* window.c		window_channel
	* To convert \" to " from the argument to /window channel so you
	  may join channels with quotes in them, eg
		/window channel "#one\"two"
		/window channel #foobar "key\"withquote"

==============================================================================
The "Evaluator" is the function that runs a block of commands that you give it.
It is the basis of the /eval command and every command you run in the language
goes through it at least once.  The evaluator may pass the commands through
expand_alias, which means support for {}s, semicolons between commands, and
$-expansion.  The evaluator may just treat the entire thing as one big command
however.  The caller sets a flag to decide this

The "evaluator" is parse_line, and it is called by the following:

* alias.c		parse_line_alias_special
	* To run a command alias's block of commands.
	* Full expansion handling 
	* $* is passed in from above

* commands.c		do_defered_commands
	* To run commands that were /DEFERed previously
	* Full expansion handling 
	* $* is saved from when /DEFER was registered

* commands.c		xevalcmd
	* To run a command through the evaluator a second time, possibly
	  in a different window or server context.
	* Full expansion handling (could result in double expansion)
	* $* is passed in from above

* commands.c		evalcmd
	* To run a command through the evaluator a second time
	* Full expansion handling (could result in double expansion)
	* $* is passed in from above

* commands.c		loader_std
	* To run one command from within a /LOADed script
	* Full expansion if /SET INPUT_ALIASES is ON (usually not though)
	* Full expansion if  /LOAD -ARGS filename ... was used
	* $* is [] if /LOAD -ARGS is not used.

* commands.c		loader_pf
	* To run an entire pre-formatted block of commands within a script
	* Full expansion handling
	* $* is [] if /LOAD -ARGS is not used.

* commands.c		redirect
	* To run commands to watch for data sent to server
	* Full expansion handling (could result in double expansion)
	* $* is passed in from above.

* commands.c		sendlinecmd
	* To run commands unconditionally as if from the command line
	* Full expansion if /SET INPUT_ALIASES is ON (usually not though)
	* $* is [] in all cases.

* commands.c		waitcmd		(/WAIT FOR ....)
	* To run commands to watch for data sent to server in 
	* Full expansion handling (could result in double expansion)
	* $* is passed in from above

* commands.c		send_text
	* To run the "AWAY" command or alias when sending a message from 
	  the input line and when away and when /SET AUTO_UNMARK_AWAY is on.
	* Full expansion handling (nothing to expand, however)
	* $* is [] in all cases

* commands.c		eval_inputlist
	* To run commands passed to /INPUT "prompt" <commands>
	* Full expansion handling (could result in double expansion)
	* $* is saved from when the /input prompt was registered

* commands.c		parse_line
	* To run the insides of {...} blocks passed to parse_line.
	* Full expansion ({...} are protected; no double expansion)
	* $* is passed in from above.

* exec.c		handle_fieldesc
	* To run the commands of /exec -line, -error, -linepart, -errorpart,
	  or /exec -end.
	* Full expansion (syntax forces use of {}s, so no double expansion)
	* $* is provided on the fly.

* exec.c		cleanup_dead_processes
	* To run the commands of /wait %proc -cmd {...}
	* Full expansion (could result in double expansion)
	* $* is provided on the fly.

* expr.c		next_unit
	* To run the inside of the {...} operator as a function.
	* Full expansion ({} is protected; no double expansion)
	* $* is passed in from above.

* hook.c		do_hook
	* To run the hook command body
	* Full expansion (could result in double expansion)
	* $* is provided on the fly.

* if.c			ifcmd
	* To run commands in an /IF decision block
	* Full expansion (syntax usually requires {}, so no double expansion)
	* $* is passed in from above

* if.c			docmd
	* To run commands in a /DO {...} (...) loop block
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is passed in from above

* if.c			docmd
	* To run commands in a /DO .... command block
	* Full expansion (double expansion if {}s are not used)
	* $* is passed in from above

* if.c			whilecmd
	* To run commands in a /WHILE (...) loop block
	* Full expansion (double expansion if {}s are not used)
	* $* is passed in from above

* if.c			foreach
	* To run commands in a /FOREACH head var {...} loop block
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is passed in from above

* if.c			fe
	* To run commands in a /FE loop block
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is passed in from above

* if.c			for_next_cmd
	* To run commands in a /FOR var FROM start TO end {...} loop block
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is passed in from above

* if.c			for_fe_cmd
	* To run commands in a /FOR var IN (list) {...} loop block
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is passed in from above

* if.c			forcmd
	* To run commands in a /FOR (...,<expr>,...) {...} loop block
	* To run prelim and loop iteration commands in above.
	* Full expansion (syntax requires a {}, so no double expansion)
	* $* is passed in from above

* if.c			switchmd
	* To run commands in a /SWITCH body
	* Full expansion (syntax requires {} so no double expansion)
	* $* is passed in from above

* if.c			repeatcmd
	* To run commands to /REPEAT
	* Full expansion (Double expansion if {} is not used)
	* $* is passed in from above

* input.c		send_line	(key binding) 
	* To run the command in the input prompt
	* Full expansion depends on /SET INPUT_ALIASES (normally off)
	* $* is [] in all cases

* input.c		parse_text	(key binding)
	* Runs the command argument to the binding, eg
		/bind ^X parse_command CMD ooga booga
	* Full expansion (double expansion if {} is not used argument cmds)
	* $* is [] in all cases

* keys.c		key_exec
	* Runs an alias that is associated with a key binding
	* Full expansion (double expansion if {} was not used to create bind)
	* $* is [] in all cases.

* perl.c		XS_cmd
	* Runs a command passed in from perl as if it were executed at
	  the input prompt with /SET INPUT_ALIASES OFF
	* No expansion (naturally)
	* $* is irrelevant.

* perl.c		XS_eval
	* Runs a command passed in from perl as if it were executed at
	  the input prompt with /SET INPUT_ALIASES ON
	* Full expansion
	* $* is [] in every case

* queue.c		run_queue
	* Runs a queued command when the queue itself is run
	* Full expansion (may have previously been expanded!)
	* $* is saved from when the command was put into the queue.

* screen.c		do_screens
	* Runs a command from standard input when in "dumb mode"
	* Expansion depends on /SET INPUT_ALIASES (usually off)
	* $* is [] in every case

* server.c		check_server_wait
	* Runs a command registered with /WAIT -cmd ...
	* Full expansion (double expansion if {} is not used)
	* $* is [] in every case

* tcl.c			Tcl_epicCmd
	* Runs a command passed in from the tcl commands "cmd" or "eval"
	  as in the perl case.
	* Expansion depends on the command (see perl case)
	* $* is [] in every case

* timer.c		ExecuteTimers
	* Runs commands scheduled for later execution with /TIMER time ...
	* Full expansion (double expansion if {} is not used)
	* $* is saved from when the command was scheduled

* who.c			whoreply
	* Runs commands from /WHO -LINE {....}
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is provided on the fly.

* who.c			whoend
	* Runs commands from /WHO -END {....}
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is provided on the fly.

* who.c			fake_who_end
	* Runs commands from /WHO -END {....}
	* Full expansion (syntax requires {}, so no double expansion)
	* $* is provided on the fly.

* who.c			userhost_cmd_returned
	* Runs commands from /USERHOST <nicks> -CMD ....
	* Full expansion (double expansion if {} is not used)
	* $* is provided on the fly.


#end of file