Variables plugin for Miranda IM v0.2.2.0 unregistered@users.sourceforge.net --- About --- This plugin doesn't add any functionality on itself. But other plugins can use it to format a string which contains variables. Since this plugin can be quite complicated to use, please read this document carefully before reporting any problems. Many thanks to HeikoH and DeathDemon for their suggestions and help. --- Usage --- Variables requires Windows 2000 or higher, and the unicode version requires the unicode version of Miranda. The Variables plugin allows you to use special formatting of strings within plugins that process their strings using this plugin. Examples of such plugins are NewAwaySys, Tipper, SimpleAway and StartupStatus. Please refer to the documentation of the plugin whether or not Variables is supported. Usually, there is no special action needed to use a formatting string instead of a normal string. A formatting string consists of 'tokens', special keywords which are translated by the Variables plugin into some text. Popular use of Variables is to show the currently playing song in your away message. If your away message module (like NewAwaySys) supports the Variables plugin, you can enter a text like the following to show your current Winamp song in your away message: "Hi, I'm listening to %winampsong%.". In this example, the token '%winampsong%' will be translated by the Variables plugin into the current song. Please see the notes for more details. Such special keywords, or tokens, are there in two flavors. First, there are fields, the syntax for a field is %fieldname%, an example is the already shown %winampsong% field. A field takes no arguments. A but more advanced is the second flavor, functions. Functions are usually accessed by "?functionname(argument1,argument2,...)", a function can take zero or more arguments. An example of a function is "?add(1,1)", this function will, as you can guess, be replaced by the number "2". A complete list of tokens can be found by pressing "Help..." on the Plugins->Variables options screen. Next to the % and ? character, there are a few others which have a special meaning, these are: !function This will parse the function given the arguments, but the result will not be parsed again. Example: "Message waiting: !message(,first,rcvd,unread)". In case you use "?message(,first,rcvd,unread)" and the message would be "You should use the string %winampsong% to get the song.", the result could be "Message waiting: You should use the string DJ Mike Llama - Llama Whippin' Intro to get the song.". `string` This will not parse the given string, any function, field or special character in the string will shown in the result without being translated. Example: "Use `%mirandapath%` to show the installation path." It's usually a good idea to put any non-special keyword between ` characters. #comment This will add a comment in the formatting string. Everything from the # character to the end of the line will be removed. Example: "%dbprofile% #this is a useless comment." The Variables plugin allows you to build much more complex formatting strings than the one shown above. Please refer to the "Additional Help" and "Notes" sections at the end of this document for more information. There are a few settings in the options dialog: [] Automatically strip "end of line" characters This will remove any CRLF or LF characters. You can insert them using the crlf function. [] Automatically strip white characters This will remove any white space. You can add white spaces by placing ` characters around them (see above). [] Automatically strip all non-parsing characters This will remove any characters that don't have a special meaning (all characters except those shown above). Basically this means you have to put all text besides tokens and comments between ` characters (see above). [] Parse the following string at startup The input box below this option is not just for testing, you can choose to parse the string at startup to set your global variables using the put and puts functions (which aren't different in this case). Also, you can created aliases using the alias function. [] Auto parse Normally the string is only parsed when you press the "Parse" button, check this to keep the parsed string updated every second. [Help...] Pressing this button shows up a list of available functions and fields. --- Additional Help --- As stated before, this plugin can be quite complicated to use, here follows some addition help for some of the complex functions. --- if(x,y,z) --- The Variables has several functions based on logics. The if function will show string y in case x evaluates to true, and z otherwise. The return values of the several logic functions can be found in the help dialog. Also, a string x is false in case an error occurs while parsing it. Example: !if(%winampsong%,`winamp is running`,`winamp is not running`) --- cinfo(x,y) --- x specifies the contact (see notes). y specifies the info you want to retrieve, the following values are possible: first, last, nick, cnick, email, city, state, country, phone, homepage, about, gender, age, firstlast, id, display, protocol, status, intip, extip, protoid From Miranda IM v0.4.3.0 Test Build #55, the following are also available: fax, cellular, timezone, mynotes, bday, bmonth, byear, street, zip, lang1, lang2, lang3, coname, codept, copos, costreet, cocity, costate, cozip, cocountry, cohomepage Example: !cinfo(,nick) --- lsdate(x,y) lstime(x,y) lsstatus(x) --- These functions require LastSeen or ContactsEx to be installed. --- lsdate(x,y) cdate(x) --- The format argument can be formatted using the following: d Day of month as digits with no leading zero for single-digit days. dd Day of month as digits with leading zero for single-digit days. ddd Day of week as a three-letter abbreviation. dddd Day of week as its full name. M Month as digits with no leading zero for single-digit months. MM Month as digits with leading zero for single-digit months. MMM Month as a three-letter abbreviation. MMMM Month as its full name. y Year as last two digits, but with no leading zero for years less than 10. yy Year as last two digits, but with leading zero for years less than 10. yyyy Year represented by full four digits. gg Period/era string. This element is ignored if the date to be formatted does not have an associated era or period string. --- lstime(x,y) ctime(x) --- The format parameter can be formatted using the following: h Hours with no leading zero for single-digit hours; 12-hour clock. hh Hours with leading zero for single-digit hours; 12-hour clock. H Hours with no leading zero for single-digit hours; 24-hour clock. HH Hours with leading zero for single-digit hours; 24-hour clock. m Minutes with no leading zero for single-digit minutes. mm Minutes with leading zero for single-digit minutes. s Seconds with no leading zero for single-digit seconds. ss Seconds with leading zero for single-digit seconds. t One character time-marker string, such as A or P. tt Multicharacter time-marker string, such as AM or PM. --- subject --- This field returns a string in the format , the contact associated with this token depends on the plugin which uses it. --- extratext --- This field returns a string depending on the plugin which uses it. --- get(x) put(x,y) puts(x,y) --- Put and puts will store string y under name x. Puts will return nothing, while put returns the string stored. Get will retrieve the value stored earlier with put or puts. NOTE: The stored string is first parsed, this means calling for example !puts(time,!ctime()) and later !get(time) will always return the time at which puts was called. Use !alias(x,y) to store 'unparsed strings'. NOTE2: Strings stored using put and puts can always be accessed (they are shared amongst instances). So beware you don't modify a variable in two places (unless you want that to happen). --- alias(x,y) --- Stores an alias named x with the value y. The alias x can be used as a regular token. You can also override existing tokens using the alias function. Example: !alias(song(pl,st,pa,nr),!switch(?if(!and(%winampstate%,%winampsong%),%winampstate%,`Not Running`),`Playing`,pl,`Paused`,pa,`Stopped`,st,`Not Running`,nr)) This line above will add a token "song" which takes 4 arguments. The first one is the string when Winamp is playing a song, the second when stopped, the third when paused and the fourth argument specifies the string when Winamp is not running. You can use it like this: ?song(%winampsong%` is playing`,`just stopped listening to `%winampsong%,%winampsong%` <- paused`,`Winamp is not running`) --- message(x,y,z,w) --- Retrieves a message for contact x according to y,z and w. y = either "first" to retrieve the first message or "last" (default) to get the last one. z = either "sent" to retrieve a sent message or "rcvd" to get a received one. w = either "read" to get a message you already read, or "unread" to get one from the message queue. Only used when z = "rcvd". If an argument is not given, this function will retrieve the message according to the rest of the arguments. Some examples: !message(,`first`,`rcvd`,`unread`) This is 'normal' operation, to get the first message in the message queue. !message(%subject%,`last`,`rcvd`,`unread`) Get the last message you received from the contact %subject%, which is in the message queue. !message(%subject%,`last`,,) Get the last message from contact %subject%. This one could be sent, received, read or unread. !message(,,,) Get the last message Miranda processed. --- for(w,x,y,z) --- Generates a for-loop; w will be initialized, x specifies the condition on which y will be executed and z will be shown. Example: !for(!puts(i,0),!not(!strcmp(!get(i),3)),!puts(i,!add(!get(i),1)),i=!get(i)!crlf()) --- Notes --- 1) Whenever a functions requires a contact as an argument, you can specify it in two ways: - Using a unique id (UIN for ICQ, email for MSN) or, a protocol id followed by a unique id in the form , for example or . - Using the contact function: --- contact(x,y) --- A contact will be searched which will have value x for its property y, y can be one of the following: first, last, nick, email, id, display Example: ?contact(miranda@hotmail.com,email) or ?contact(Miranda,nick). Contact will return either a unique contact according to the arguments or nothing if none or multiple contacts exists with the given property. If a property holds for multiple contacts, you can select one of those contacts by adding an extra argument z. This indicates which contact to use. The ?ccount function can be used to find out how many contacts hold for a certain property. The following formatting string demonstrates the use of ccount and contact with three arguments. Example: # get the number of contacts with the display name "Marley" !puts(count,!ccount(`Marley`,display)) # loop through these contacts, for each of them, show the e-mail address !for(!puts(n,0),!not(!strcmp(!get(n),!get(count))),!puts(n,!add(!get(n),1)),!cinfo(!contact(`Marley`,`display`,!add(!get(n),1)),email)) In case the z argument is used, y can be any property of the cinfo function. Z can be 'r' to get a random contact. 2) The %winampsong% field will only retrieve a song for Winamp, for Foobar2000, I recommend using foo_text (http://members.lycos.co.uk/musicf/) and the txtfile function. 3) The variables regexp_check and regexp_substr are only available if you have pcre.dll or pcre3.dll in your miranda directory (or system32). PCRE is available from the "external" folder in this package and/or from http://www.pcre.org/ 4) Variables v0.2.0.0 syntax is inspired by the TAGZ system used in Foobar2000, http://www.foobar2000.org/. --- Changelog --- 0.2.3.4: - added ?cinfo(<>,account) -> gets the account name under 0.8.x and later 0.2.3.3: - memory leak fix 0.2.3.2: - adaptation for Miranda 0.8 0.2.3.0: - temporary variables were added by Ricardo Pescuma Domenecci - fixes for memory leaks & crashes 0.2.2.0: - Added service MS_VARS_GETSKINITEM (V icon by Faith Healer) - Added option to remove white spaces and other non-parsing characters - Change in parsing routine: fields (%field%) are not parsed by default, use ?noop(%field%) instead - Change in parsing routine: fields won't be parsed with function chars anymore and vise versa - Added function strmcmp, amipvar, amipformat, noop, protoname, ls - %subject% supports contacts without uniqueid (please test) - txtfile now supports unicode text files - Performance gain (only if you use HUGE strings or rapid parsing) by using (Bob Jenkins') hash function - Lots of bug fixes 0.2.1.0: - Lot of bug fixes, unicode version, extended API, much more 0.2.0.0: - Build from scratch 0.1.0.0: - First release --- Disclaimer --- If something terrible happens, don't blame me.