DOCUMENTATION FOR JS4MIRC (FOR INSTALLATION SEE README.TXT) ======================================================================= Last update on June 26th 2008 for version 1.0 0. FAQ > What is "supported mode"? > What can Javascript do? > Why do I get 'XMLHttpRequest is not defined'? > How do I manipulate the DOM? 1. RUNNING JAVASCRIPT > Invoking the interpreter > Notes on $dllcall and asynchronous calls > Embedding Javascript into events/aliases > Caching embedded code 2. JAVASCRIPT FUNCTIONS > mirc object > __get__(identifier) [Property Accessor] > eval(string) > vars object > __version__ > scripts object > parse(file, line) > invoke(file, line, cache = false) > load(filename) > alert(string) or print(string) 3. MIRC ALIASES (DEFINED IN JS.MRC) > /js_shell > /js | $js() > /js_eval() | $js_eval() > /js_eval_raw() | $js_eval_raw() > $js_str() > $js_dll > /js_unload 4. MIRC SIGNAL CALLBACKS AND OUTPUT HANDLING > JS_LOADED > JS_ERROR > JS_EXCEPTION 5. E4X SUPPORT 6. REFERENCES ======================================================================= 0. FAQ > What is "supported mode"? JS4mIRC relies on the CLB (Common Language Bridge) which is part of the Dynamic Languages 4 mIRC project. The CLB extends the way a DLL can communicate with mIRC, enabling it specifically to be able to access event specific identifiers, like $opnick in the ON OP event. In addition to extended functionality, this mode is roughly 3 times faster than using the standard SendMessage API documented in the mIRC help (/help SendMessage). However, a drawback of this mode is that it requires specific knowledge about the makeup of the mIRC binary that is being run. In other words, to make use of the CLB's extended functionality, the version of mIRC used with the DLL must be explicitly supported by the CLB, hence "supported mode". CLB is able to fallback on the standard SendMessage API when the version of mIRC is not supported, but beware that you may be using a script that requires the extended functionality that the CLB provides. If you are using JS4mIRC in unsupported mode, verify that you do not have any embedded scripts inside events that make use of event specific identifiers. In such a case, your events will not function properly. > What can Javascript do? Supposedly you are already familiar with Javascript as a language, and yet this question is still valid. In fact, the more you know about JS, the more reasonable this question is. JS4mIRC utilizes the SpiderMonkey[1] Javascript interpreter engine by Mozilla Foundation. This is the same core engine that is utilized by Mozilla Firefox, however there is a clear distinction between Javascript in Firefox and Javascript in mIRC. Firefox implements many browser-specific bindings for the language, namely the entire DOM, which is usually the only thing most Javascript programmers ever see (when programming for the web). None of this exists in the low-level Spidermonkey engine. The only support Spidermonkey provides is the ECMAScript standard[2] which defines a few simple object types (String, Array, regular expressions, E4X). There is no socket support or filesystem support. However, because the implementation is so small, it makes it highly useful for scripts that need to perform common processing very fast. The SpiderMonkey engine is extremely lightweight, making it ideal for simple and fast scripting. One example would be downloading an XML document using mIRC sockets and then parsing it with Javascript's highly optimized XPath and E4X support. > Why do I get 'XMLHttpRequest is not defined'? See the above note about Javascript's builtin support for sockets; there is none. The XMLHttpRequest object is part of the W3C standard aimed at browser implementations, not ECMAScript. There are no plans to support this object in the near future. > How do I manipulate the DOM? What DOM? The Document Object Model applies only to browsers and has no place in an IRC client. You can, however, use E4X to manipulate XML objects. See the E4X section below. 1. RUNNING JAVASCRIPT * Note all functions listed here are documented fully in sections 2 and 3. > Invoking the interpreter The easiest way to run Javascript code is to simply call: /js CODE_HERE * Note that /js is a convenience alias specified in js.mrc You can also use $js(CODE_HERE) to retrieve the return value from a block of JS code. This will convert any Javascript native types to mIRC equivalents, meaning `true` will turn into $true, `false` into $false and null will turn into an empty string (mIRC has no real concept of null values). You can use $js_eval_raw() to do no type conversion on the data. > Notes on $dllcall and asynchronous calls Don't use it. The version of SpiderMonkey distributed with this DLL was not compiled with JS_THREADSAFE and is therefore not thread safe. If you use $dllcall you will find yourself at the mercy of the interpreter, and things *will* go wrong. > Embedding Javascript into events/aliases Most people don't just want Tcl sitting on the sidelines while mIRC does its thing. For this reason, you have the ability to embed your JS code directly into your mIRC scripts seamlessly. if $($has_js,2) { // JS Code here alert("I'm using js4mirc v" + mirc.__version__) } You can call any event specific identifiers as you normally would via script, however you do not have access to local mIRC variables. For example: ON *:TEXT:*:#: { set -u0 %text $1- if $($has_js,2) { alert(mirc.nick() + " just said " + mirc.vars.text + " in " + mirc.chan()) } } Notice that $1- is not available to JS4mIRC and that %text must be a global variable, not local. > Loading Javascript files While JS has no native functionality to load files on a filesystem, JS4mIRC does. This ability is made available in two different ways. The first is /js_load_file: /js_load_file FILENAME Do not quote the filename. Secondly, you can call the `load()` function from inside Javascript to do the same thing, however this is slightly less efficient and you should only do this if your JS needs to load files dynamically. > Caching embedded code You can also use $has_cached_js in place of $has_js in the above examples. This will not re-parse your Javascript code, making for faster execution time (that's why you're using JS, right?). You should only enable this when you're sure your code won't change, however, because once it's set, a change to the embedded code will not be registered until the DLL is unloaded. You can, however, revert your code back to $has_js to have it re-parse the code without unloading the DLL. 2. JAVASCRIPT FUNCTIONS > mirc object: > __get__(identifier) [Property Accessor]: You can call any mIRC identifier by executing: mirc.identifiername(...arguments...) Example: mirc.nick(mirc.chan(), 1) ; Equivalent to $nick($chan, 1) If the identifier in mIRC takes no () you must still specify them in JS since this is the only way to call a function. > eval(string, [times]): NOTE: This function is aliased as mirc(...), which is the shorter form. Evaluates `string` as mIRC code `times` times. Similar to calling $eval from mIRC, however it will evaluate text as a command if no $/% prefix is found. The `times` argument specifies how many times the text is to be evaluated, 0 if no evaluation is to be performed. Example: mirc.eval("$me") ; returns MYNICKNAME mirc.eval("echo -a hi $me", 0) ; will echo "hi $me" (literally) > vars object: Access the properties on this object to transparently do lookups in mIRC's variables table. Example: mirc.vars.x = 2 ; Equivalent to /set %x 2 mirc.vars.x ; Equivalent to getting the value of %x mirc.vars['x'] ; Javascript syntax meaning the same thing delete mirc.vars.x ; Equivalent to /unset %x > __version__: Returns the version of JS4mIRC. > scripts object: > parse(file, line): Parses embedded code starting at `line` in `file`. Returns the contents as a String. > invoke(file, line, cache = false): Parses the embedded code at `line` in `file` and then executes it. If `cache` is set to true and the code was previously parsed, the previously parsed code is executed instead. > load(filename): Loads a filename as a Javascript script. > alert(string) or print(string): Because Javascript has no standard input/output, this is the easy way to echo contents to mIRC. alert(STRING) is equivalent to /echo -a STRING. 3. MIRC ALIASES (DEFINED IN JS.MRC) > /js_shell Starts a Javascript interactive shell > /js | $js() Evaluates as Javascript code. See /js_eval for details. > /js_eval() | $js_eval() Evaluates as Javascript code. The return value of $js_eval is the last executed Javascript statement converted into an mIRC type if there is one. For example, $js_eval(false) will return $false, not "false". > /js_eval_raw() | $js_eval_raw() Same as $js_eval but does no type conversion when returning the value. Used when you want $js_eval_raw(true) to return "true" instead of $true. > $js_str() Quotes a string of text like $qt but escapes any ' or \ characters so the return value would be safe to be used as a Javascript String. > $js_dll Returns the location of the js4mirc.dll file. > /js_unload Unloads the dll. 4. MIRC SIGNAL CALLBACKS AND OUTPUT HANDLING JS4mIRC sends a few signals to mIRC now and then that can be caught by the scripter. For more information on the SIGNAL event, read mIRC's help under "ON SIGNAL". The following signals are supplied: > JS_LOADED Triggered when JS is finished loading into memory. You can use this to load any important JS support libraries. The identifier $1 will be filled with the "supported mode" value as $true / $false (whether or not the CLB is running in supported mode). See "supported mode" in the FAQ for more information on this value. > JS_ERROR This signal will be triggered in the rare case where the CLB cannot communicate with mIRC. This is a critical error and should be handled by halting further script processing. Error details will be filled into $1-. > JS_EXCEPTION Triggered when Javascript propagates un unhandled exception up to JS4mIRC. Exception details will be filled into $1-. 5. E4X SUPPORT E4X is ECMAScript support for embedded XML inside Javascript. It's a relatively new functionality implemented by SpiderMonkey. It gives Javascript native XPath and XML parsing capabilities using a transparent syntax. It can be exemplified by the following sample code found on the E4X Wikipedia page[3]: var sales = ; alert( sales.item.(@type == "carrot").@quantity ); alert( sales.@vendor ); for each( var price in sales..@price ) { alert( price ); } You can read more about how to use E4X on the Wikipedia page. 6. REFERENCES [1] SpiderMonkey: http://developer.mozilla.org/en/docs/SpiderMonkey [2] http://www.ecma-international.org/publications/standards/Ecma-262.htm [3] http://en.wikipedia.org/wiki/E4X