HipScript is a package of utility scripts for Ircle 3.0.4 and later versions. It provides quiet automation of mundane IRC tasks for users and channel ops. It does not provide any war commands, channel takeovers, or features a channel op might find obnoxious.
HipScript is a plugin-based scripting package which allows users to choose which features they need, and also allows them to code their own plugins (or obtain them from other sources). HipScript is delivered with over a dozen standard plugins; there is no limit to how many plugins may be loaded at once, other than memory and processor power available to run them all.
HipScript is fully connection-aware; all features work properly no matter how many connections you have open at once.
Some of the major features of the standard plugins include
All HipScript configuration is done thru the /commands described for each plugin. Configuration data is automatically saved whenever you quit Ircle or unload HipScript, in IrcleScriptFolder:MyHipPrefs:HipScript.config for Ircle 3.0, or in Application Support:Ircle:Script Data for Ircle 3.1. You cannot edit the config file by hand; it is stored in a binary format. It's a good idea to occasionally make a backup copy of the config file.
HipScript never does anything "behind your back". Some scripts use Ircle's "/quote command" feature to enter commands or talk to other users in ways that you can't see. Whenever HipScript talks to another user or invokes an IRC or Ircle command, it does so only based on options you've activated, and it shows you what it's doing. Sometimes this leads to a bit of window clutter, but you're guaranteed: No suprises.
You may freely give the distribution archive to other users, but please keep the package intact, docs and all.
HipScript is delivered as a set of compiled scripts with source code included. Users are encouraged to use the source code to learn Ircle scripting if they choose, and accomplished scripters are free to use the code or techniques from the HipScript package for their own scripts.
The entire package is freeware, and all rights are explicitly released. I would like to request that if you redistribute the package under the HipScript name, you do so only in the form of the complete distribution archive including all sources and documentation.
As a warning to users, accept HipScript only in the form of compiled scripts with source code included. If someone gives you a run-only version of HipScript or any of its standard plugins, they are not genuine, and there's a good chance they're trying to lay a virus or trojan on you.
Nothing prevents scripters from creating their own plugins that are distributed in run-only format. I would like to strongly discourage this by requesting that users refuse to accept or run any HipScript-compatible plugin that is distributed in run-only format. A run-only script (or plugin) could contain any sort of evil system-damaging code, and you would have no way of knowing that. Also, the world needs more source code examples of Ircle scripting.
As of 07/01/2001 the main HipScript module is too big to open with the standard AppleScript Editor. The file is still distributed in source code format, but you won't be able to look at the source code unless you get yourself one of the other AppleScript editors available on the market. One good choice for this is the free Smile editor, you can find it by searching for Smile at www.versiontracker.com. HipScript updates are also listed on VersionTracker for your convenience.
You must be running Ircle 3.0.4 or later to use HipScript.
You must be using System 7.5 or later. (HipScript requires the Scriptable Finder).
You must give the Ircle application at least 4000k of RAM to run HipScript. The installer will automatically increase the memory assigned to Ircle as needed.
As of HipScript release 981012a, the installation is automated by an Install script. It is no longer possible to "hand-install" HipScript; you MUST use the installer.
If the load time is unacceptably slow, consider disabling some of the plugins you may not need (see Performance Tips, Speeding up load times, and /disable). A PowerMac 604e/200 loads all the standard plugins in under 10 seconds; a 68040/33 can take over a minute. The long load time is a side effect of how AppleScript loads the plugins; everything runs pretty fast once it's all loaded.
To get the most value from HipScript's automation features, you can set it as your startup script in the Ircle config. Open the Ircle preferences, and under the Scripts tab, click on the Select button for the startup script, and select HipScript.
If you are a DalNet user, see the /dalnick and /dalchan commands. These commands allow to you configure your registered nicknames and channels to activate the DalNet automation features.
There are many configuration values you may set to tailor the automated features of various plugins. These are described in the sections for each plugin. By default, all features are initially configured to be "unsurprising" -- clones will not be kicked until you set a limit with the /clonelimit command, etc.
If you get prompted to locate the application "Ircle 3.0.4" every time the script loads, open HipScript with the AppleScript editor by double-clicking on it. (You have to give the AppleScript editor at least 4096k of memory to open HipScript.) With the cursor on the first line of the script (an empty line), hit the space bar, then hit the Check Syntax button in the editor window. The editor will prompt you to locate Ircle 3.0.4 -- locate the app, then save the script, and it won't ask you anymore. (If Onno would quit changing the name of the Ircle app, I think this wouldn't keep happening.)
You must use the supplied Install script to upgrade to new releases of HipScript. The installer will preserve all your existing config info, and the contents of your MyHipPlugins folder, where 3rd-party plugins are stored. You can run the installer to upgrade hipscript without quitting Ircle. In fact, it's better that you do so, it will upgrade faster. Every once in a while, I make a change to the HipTools scripting addition, and the upgrade will need to reboot your machine; in this case you will be told about that and given an option to quit the installer.
HipScript attempts to load the standard plugins from a folder called HipPlugins in the Ircle scripts folder. It also attempts to load any custom plugins you've written yourself or obtained from other sources from a folder called MyHipPlugins. You should never place standard plugins into your MyHipPlugins folder.
The HipPlugins and MyHipPlugins folders cannot have other folders nested inside of them.
You may choose to use any other plugins, including those you write yourself or obtain from other sources, by simply placing those plugins into the MyHipPlugins folder. HipScript itself is only a plugin manager, it provides no services of its own; there is no point to running HipScript with no plugins.
The recommended method for managing which plugins get loaded is the /disable command. You can also move plugins in and out of your MyHipPlugins folder, or rename files to begin with a ~ character to prevent them from loading. The /disable command is by far the most convenient method; the ~ method is supported for compatibility with older versions.
If you use a plugin for a while, then stop using it, then re-enable it, all the configuration settings (if any) for that plugin will remain intact in the myHipConfig.data file while the plugin is disabled.
Standard plugins which are distributed with HipScript all begin with the 3-letter prefix "hip". I have asked developers of HipScript-compatible plugins to name their plugins using the prefix "hcp" (for HipScript Compatible Plugin), or indeed anything they want except "hip". I also recommend that if you write your own plugins, use a prefix of "my". If, for example, you decide to modify the "exampleBartender" plugin for your own use, rename it to "myBartender", and move it to the MyHipPlugins folder so it doesn't get wiped out by future upgrades.
The installer also creates a folder called MyHipPrefs; the standard HipScript configuration file is stored in here, and 3rd-party plugins may store additional config data of their own in here as well. It's a good idea to make a backup copy of your config occasionally. Note that as of Ircle version 3.1b10r3, HipScript prefs are stored using Ircle's new script data storage feature. In this case, the preferences are stored on your boot drive, in the folder "Application Support:Ircle" in a pair of files named "Script Data" and "Script Data.idx".
The installer also creates a pair of folders named HipPluginSupport and MyHipPluginSupport. These folders are used to store scripts and modules not directly loaded as plugins, but used by some of the loaded plugins. For example, a plugin that has a separate GUI handler might store it in the MyHipPluginSupport folder.
There are two required plugins which must always be present, named hipScriptLib and hipScriptLib2. They provide services to HipScript and all other plugins. Another plugin that is pretty much required is hipDelayedCommands; other plugins (especially the hipDalnet plugin) get some of their work done by scheduling a delayed command.
The plugins you choose to run can make a difference in Ircle and HipScript performance.
Another method of speeding up the load time for plugins is a bit complex, but it can cut the load time by 30-50%: re-save all the plugins as run-only scripts. I distribute HipScript in source form partly so that people see for themselves that there's nothing evil or virus-like in it. But, there's no reason why you can't convert the plugins to run-only yourself for better performance.
Warning: Run-only means just that! Once you've saved a file as run-only, you can never ever look at its source code again. If you use the run-only method on plugins that are not part of the standard distribution, make sure you have source copies somewhere! You have been warned -- I don't wanna hear any whining about how you lost your only copy of the source to some cool plugin you wrote.
Here's the procedure:
I would love to automate the process of converting all the plugins to run-only, but the AppleScript editor itself is not a scriptable application. Go figure.
/disable
/disable moduleName
/disable -moduleName or -number
This command disables or re-enables plugins.
Used with no parameters, it displays the list of plugins currently disabled.
Used with just a module name, it adds that name to the list of plugins that will NOT be loaded by HipScript. The command doesn't check to ensure that the name you supply matches any existing plugin modules.
Used with -name or -number, it removes that name from the list of disabled plugins, allowing that plugin to be loaded again in the future.
Any changes made to the list take effect the next time HipScript is loaded. There is no way to dynamically load or unload individual plugins without reloading all of HipScript.
This command replaces the old plugin management notion of renaming the file to begin with a ~ character. With the old method, you had to manually rename the plugins you wanted disabled each time a new version was released. With the new method, you can just replace the old HipPlugins folder with the new one from a distribution archive, and whatever plugins are in the disabled list will continue to be disabled without any further action on your part.
/pal
/pal nickname palname
/pal -nickname
This command creates, deletes, or lists entries on your pals list.
Used with no parameters, this command lists the entries on your pals list.
Used with -nickname it removes an entry from your pals list.
Used with a nickname and palname, it creates an entry and establishes the "nicknick" name for the pal.
A nicknick name is a shorter version of a nickname. The theory here is that if you have a friend whose nickname is JoeBlow, but you always call him Joe when talking to him, you can create a pal entry and set Joe as the palname for the JoeBlow nickname. Then, whenever an autogreeting applies that contains the $lastjoiner variable, the palname (JB) will be used in place of the full nickname.
Currently the pals list is used by the auto-greeter and tab nick completion with the Pals option turned on. Some day, other parts of HipScript may have access to the pals list and will use palnames when addressing users (for example, a bartender plugin might do this).
If you don't have a shortened form of a name but still want the user on your pals list for autogreet purposes, just use the regular nickname as the palname.
/save
This command causes all config data in all plugins to be saved immediately. Normally, config data is automatically saved whenever you quit Ircle or unload/reload the script. If you've just made big changes to your config, you can use this command to force a save to protect from crashes or whatever. (Ircle crash? Naw....)
Note that as of this writing (01-15-2000) all standard HipScript plugins respond correctly to the /save command, but some 3rd-party plugins might not do so. Their config will still auto-save at quit/unload time, but may not be saved right away when you do /save. I expect the 3rd-party plugin writers will add this feature to their plugins pretty quickly.
/showcolor [number]
This command sets the color used by all HipScript output. Whenever the script or its standard plugins display information, each line is prefixed with "•••". You can also set a color to help make the script output stand out.
Valid color codes range from 0 thru 26, with 0 being the default "echo blue". If you don't enter a number, the current setting is shown.
/showprefix [characters]
This command sets the prefix at the front of every line displayed by HipScript and its plugins. By default, the prefix is "••• ". You can set it to any other string you'd like; it will appear in the color set by the /showcolor command.
This happens only online, in the #Macintosh channel on DalNet. (Recommended servers, twisted.dal.net or tsunami.dal.net). I don't publish my email address, real name, or other personal info. On the upside, I've been addicted to chat since before there was such a thing as IRC, over 10 years now; you can pretty much always find me on online in the evenings (U.S. Mountain Time).
If I tried to thank everyone who has helped with design and testing of HipScript, this section of the document would be almost as large as everything up this point.
A big round of thanks to the ops staff and regular users of the DalNet #Macintosh channel, who have been supportive and very tolerant of my "Don't mind me, I'm just testing..."
Special thanks have to go to CyberPet, for being the first one brave enough to run HipScript as her default startup script and tolerate the many bugs. And also to DigiCow and Rhino for helping me figure out a bunch of issues related to installing and running the script on OS X.
And of course, the most thanks of all to Onno, for providing us with the best IRC client for Macintosh, for providing us with script support in that client, and most of all for putting up with all my questions, suggestions, and nit-pickety bug reports. Thanks dude.