# $EPIC: push_function.txt,v 1.4 2007/03/23 16:39:05 jnelson Exp $
======Synopsis:======
$__push__(<variable name> <data>)

======Description:======
This function appends a word to the end of <variable name>.  The <data>
is considered to be **one word**.  This means if [[xdebug]] dword is turned
on, then the client will add double quotes around <data> before appending
it to the variable!

You need to turn off [[xdebug]] dword to get the epic4 behavior!

======Practical:======
Push adds a new word to the end of $<variable name>, which is considered
a variable containing a word list.  It is equivalent to the following:

<file>
@ <variable_name> #= (<variable_name> ? [ ] : []) ## data
</file>

This function is useful to append a word to the end of a word list,
which you might do to create a FIFO, LIFO, or other ordered queues.  The
reverse of __push__() is [[pop function|pop]]() and the inverse is
[[unshift function|unshift]](), while the inverted reverse is [[shift
function|shift]]().

If <variable name> doesn't exist before you __push__() something onto it,
then it is created automatically for you.

======Returns:======
The new value of $<variable name>.

======Examples:======
<file>
$push(blah hello there)            adds "hello there" to end of $blah
</file>

======History:======
This function first appeared in "+7" (post-ircII, pre-EPIC)