From 48540940b6c28bb4378abfeb500ec45a625b37b6 Mon Sep 17 00:00:00 2001 From: Vadim Dashevskiy Date: Tue, 15 May 2012 10:38:20 +0000 Subject: initial commit git-svn-id: http://svn.miranda-ng.org/main/trunk@2 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c --- plugins/variables/Variables.txt | 403 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 plugins/variables/Variables.txt (limited to 'plugins/variables/Variables.txt') diff --git a/plugins/variables/Variables.txt b/plugins/variables/Variables.txt new file mode 100644 index 0000000000..14b37e0a48 --- /dev/null +++ b/plugins/variables/Variables.txt @@ -0,0 +1,403 @@ +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) +The variables amipvar and amipformat are only available if you have +ac.dll in your miranda directory (or system32). ac.dll is available +from the "external" folder in this package and/or from +http://amip.tools-for.net/ (part of amip_sdk). You'll also need to +install one of the AMIP servers from http://amip.tools-for.net/ + +5) +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. -- cgit v1.2.3