This plugin provides an aliases feature that allows you to define your own commands. An alias is essentially a named shortcut.
It also provides an extended version of Ircle's autoexec feature, allowing you to set up HipScript commands and aliases to be executed each time you connection to a server.
And, it provides features to define your own buttons for the Ircle user window, or override Ircle's builtin buttons.
Aliases and autoexecs can use the $variables that a shortcut can use, and a few additional ones described below. You can define aliases for text to be typed into a window, irc commands, or script commands, including any other HipScript or plugin command. For example, if you think /nickfreshen is too long a command name, you can set up an alias of /nf for it.
The /gme and /gsay commands are sort-of builtin "aliases", because there would be no way to define them as a regular alias, but it doesn't make sense to have a whole separate plugin just for those two.
HipScript also supports tab-key alias completion. If you type part of an alias and hit tab, it will cycle thru the list of aliases that match that partial word.
/alias
/alias name
/alias -name
/alias name value
This command creates, deletes, or lists aliases.
If used with no parameters, it lists all existing aliases. If used with just a name, it lists the value of the alias with that name (if any).
If used with -name, it deletes the alias of that name (if any).
If a value is supplied, it creates an alias with the given name and value (or replaces the alias if one of that name already exists).
To define an alias that executes multiple commands (or types multiple lines of text), put "\n" where a line-end should appear (just like for Ircle shortcuts). An alias may execute commands that include other aliases.
Aliases may contain any of the standard $variables, similar to an Ircle shortcut.
To invoke an alias, type / followed by its name, and optionally any parameters it needs.
Bug alert: It appears that Applescript has some kind of problem with aliases that contain a '\' character, other than \n to separate lines or commands in the alias. I haven't yet been able to track this down or work around it, but including a "\." for example in an alias crashes my machine bigtime. So don't do that!
/autoexec connectionspec command(s)
This command creates, deletes, or displays HipScript autoexec commands. Ircle's autoexec commands in the Connections config window cannot execute HipScript commands or aliases. The /autoexec command solves that problem by allowing you to specify commands to execute at connection time that can include any combination of HipScript commands and aliases, or regular Ircle or IRC commands.
If used with no parameters, it lists all existing autoexecs. If used with just a connectionspec, it lists the value of the autoexec with that connectionspec (if any).
If used with -connectionspec, it deletes the autoexec commands of that connectionspec (if any).
If a value is supplied, it creates an autoexec with the given connectionspec and commands.
To define an autoexec that executes multiple commands, put "\n" where a line-end should appear (just like for Ircle shortcuts). Autoexec commands can also contain standard $variables just like aliases. (However, only $nick is really useful; the channel-specific variables such as $channel, $selecteduser, etc. will expand to nothing, since at connection time you are, by definition, not in any channels yet.)
HipScript's autoexec commands are somewhat more flexible than Ircle's autoexec feature. Ircle allows you to specify a set of autoexec commands for each connection number. HipScript's autoexec allows that, but also allows you to set up autoexecs by server or network name, including wildcards.
When the connectionspec value is a number between 1 and 10, autoexec commands are created on a per-connection basis, just like in Ircle. (Internally, the name is converted to "connection-#").
A special connectionspec of "load" can be used for commands that you want to execute as soon as hipscript is loaded, whether you're connected to any servers or not. Note that this means both when you start Ircle, and if you manually do /load hipscript to reload it.
When the connectionspec is anything other than a number, it is matched against the server name at connection time (wildcards allowed) and all autoexecs that match are executed. For example, a connectionspec of *.dal.net will match any server on the DalNet IRC network. A connectionspec of * will match any server. Be careful with server names -- you may connect to spider.dal.net, but that server's real name is spider.ca.us.dal.net. To correctly write a connectionspec for a spider connection, use spider*.dal.net.
At connection time, HipScript executes each autoexec that matches for the server you're logging on to. If you have autoexecs set up for
connection-1
*
*.dal.net
spider*.dal.net
sodre*.dal.net
*.undernet.org
And you connect to spider.dal.net on connection 1, it will execute the commands for
connection-1
*
*.dal.net
spider*.dal.net
The order of execution is 1) by connection number, 2) by all matching wildcarded or named connectionspecs, in the order they appear if you do /autoexec to list all autoexecs.
/bnum [ on | off ]
This command helps you determine the numbers of the buttons in the Ircle Users window. If you enter /bnum with no parameters, it will display the number of the next button you click on, without acting on that button, just once. If you use /bnum on it will continue to display button numbers (without acting on the buttons) until you enter /bnum off.
/button
/button -#nn
/button #nn value
This command creates, deletes, or lists button commands. Use it to create your own customized buttons for the Ircle Users window, or to override the actions of Ircle's builtin buttons with your own actions.
If used with no parameters, it lists all existing button commands.
If used with -#nn, it deletes the button command with that number (if any).
If used with #nn and a value, it defines a new button command. The #nn parameter defines the button number and, optionally, the modifier keys. Modifier keys are:
c - command (apple key)
s - shift
o - option
k - control
Specify modifier keys by adding + and the letter(s) after the number (no spaces). The letters must appear in the order "csok" if more than one is used at a time (leaving out any you don't need). For example:
/button #81 /echo This is Script Button 1
/button #81+o /echo This is Script Button 1 with Option held down
/button #82+co /echo This is Script Button 2 with Command and Option both held down
You can use the /bnum command to figure out what a button's number is.
The value for a button command can be any Ircle command, HipScript command, alias, or just text to be typed. Button commands may contain any of the standard $variables, similar to an Ircle shortcut. To define an button command that executes multiple commands (or types multiple lines of text), put "\n" where a line-end should appear (just like for Ircle shortcuts).
There is also a feature to allow a button click to prompt you for additional text via a popup dialog box. Just include in the command string, %prompt(Prompt msg goes here). When you click on the button, you'll get a popup dialog with the prompt message. Whatever you type in the dialog gets placed into the command in place of %prompt(). If you want to supply a default text-entry value, use %prompt(Prompt msg|Default value).
Bug alert: It appears that Applescript has some kind of problem with aliases that contain a '\' character, other than \n to separate lines or commands in the alias. I haven't yet been able to track this down or work around it, but including a "\." for example in an alias crashes my machine bigtime. So don't do that!
Aliases can use the same predefined variables as Ircle's shortcuts, and some extra ones.
$nick
Your current nickname [1]
$oldnick
The last nickname you used if you've changed since you logged on
$channel
The current channel name [1]
$con
The current connection number.
$selecteduser
The nickname of the first selected user in the current channel [1] [2]
$lastjoiner
The nickname of the last person to join the current channel [1] [2]
$lastmsger
The nickname of the last person to send you a message on the current connection [2]
$lastctcper
The nickname of the last person to CTCP you on the current connection [2]
$lastparter
The nickname of the last person to part (including signoff) the current channel [2]
$lastquitter
The nickname of the last person to signoff the current connection [2]
$lastnickchanger
The nickname of the last person to change nicks in the current connection [2]
$lastdelayedcmdnum
The number of the last delayed command scheduled
$lastban
The nick!user@host of the last ban ANYONE (including you) set in the channel [2]
$mylastban
The nick!user@host of the last ban YOU set in the channel [2]
$lastkick
The nick of the last kick ANYONE (including you) did in the channel
$mylastkick
The nick of the last kick YOU did in the channel
$date
The current date (formatted as per your Date & Time control panel prefs) [1]
$time
The current time (formatted as per your Date & Time control panel prefs) [1]
$*
Everything typed after the alias name on the command line
$1, $2 ... $9
The 1st word, 2nd word, etc., typed on the command line
$1-, $2- ... $9-
The 1st and all following words, 2nd and all following words, etc.
[1] These variables can be used in /greet commands.
[2] These variables all have additional variations formed by adding a suffix to the variable name.
Using $selecteduser as an example:
$selectedusernick
The nickname (the part before the !)
$selectedusername
The username (the part between ! and @ in nick!user@host)
$selecteduserhost
The hostname (the part after the @)
$selectedusernickmask
The nickname as a smart-wildcard (this is pointless, tom->tom)
$selectedusernamemask
The username as a smart-wildcard (EG, tom->*tom*)
$selecteduserhostmask
The hostname as a smart-wildcard (EG, ppp23.tnt2.uu.net ->ppp*.tnt*.uu.net)
When a numeric variable such as $3 appears, the third word (if 3 or more exist) typed after the alias name is substituted. If the variable appears as $3- then the third thru last words are substituted (that is, the dash means "and the rest..."). For what it's worth, $* and $1- are equivalent.
For variables described as "on this connection" that means the connection of the window the alias was typed into.
In addition to the standard $variables, plugins written by 3rd parties can now supply $variables as well. These variables will take the form $(variablename), but otherwise may be used in the same way as the standard $variables.
/echo any text string
This command echoes the text string locally without sending it to the server. It's useful mainly in aliases.
/gme <some words here>
/gsay <some words here>
These commands will say something, or /me something, in every open channel and dcc chat of every open connection. They differ from the /broadcast command primarily in that they work in dcc chat connections as well as channels.
Note: a bug in Ircle prevents the text from echoing locally in a dcc chat window, but the user on the other end does see the text.
/gconinput <words or commands here>
/gschaninput <words or commands here>
These commands are similar to the /gsay command, except that with these you can also include hipscript and irc commands, and they don't do anything in DCC connections, only server connections. /gconinput runs the commands once in every connection that's open. /gchaninput runs the command in every channel of every connection that's open.
Any standard $variables you use in the commands will be resolved properly for the channel and/or connection the command is running in. When the command is part of an alias, however, the interaction with $variabes is more complex. Hang onto your hat, this is a wild ride...
When you run an alias, any $variables it contains are resolved right away, before running any of the commands or outputing any of the text of the alias. So if you have an alias called mynick that does /gconinput /echo $nick then the $nick gets resolved right away to the nick for the connection you typed the /mynick command into, and then that same string gets echoed once per connection. Probably not useful.
However, when an alias is resolved, a pair of dollar signs resolves to a single dollar sign. So, if you defined the alias as /gconinput /echo $$nick, then when you type /mynick it resolves to /gconinput /echo $nick. Then when the /gconinput command runs that string in each connection, the $nick it contains is resolved for each connection, echoing the nickname you are using in each connection.
Okay, so how might you use this in the real world? One way would be the feature I added these commands for: doing global away/back aliases that change your nick in the process. Like this:
/alias myaway /gaway $*\n/gconinput /nick $$nick_away
/alias myback /gaway\n/gconinput /nick $$oldnick
With that pair of aliases, typing /"myaway for a while" will do a /gaway for a while (announcing your awayness in all connections), then in each connection it will change whatever nick you're using to thatnick_away. Typing "/myback" will announce your return, and change your nick back to the nick you were formerly using in that connection.
/playsound soundfilename
This command plays a sound file locally without sending it to a user or channel. It's useful mainly in aliases. For example, you can set up an "autogreet" for a channel that both greets a joiner and lets you know that someone has joined:
/greet #MyChannel public "/playsound page.wav\nHiya $lastjoiner"
If Hippie defines an alias as:
/alias late Well $selecteduser, it's $time here.\nI have to $*
Then, with user Joe selected in the user window he types:
/late go pick up the kids.
Then what will appear in the channel is:
Well Joe, it's 4:00pm here.
I have to go pick up the kids.
When you get tired of typing /delay #6 cancel or /delay #3 -2:00 to cancel or reschedule a delayed command (such as an auto-unban), you might find aliases such as these handy:
/alias dcan /delay #$1 cancel
/alias dadj /delay #$1 $2-
Then you can type /dcan 6 or /dadj 3 -2:00.
An example of using an alias that invokes another alias might be:
/alias ms /msg memoserv@services.dal.net $*
/alias mread /ms read $1
/alias mdel /ms delete $1
If you type /mread 1 it will do:
/msg memoserv@services.dal.net read 1
Be careful not to define an alias that invokes itself! For example:
/alias dumb /dumb
This will get you stuck in a loop until you get a "stack overflow" error. (Hint: cmd-period will break out of the loop.)
To ensure that's you're always invisible even on servers that don't support Ircle's method of setting auto-invisible specified the Connections window config, use:
/autoexec * /mode $nick +i