Variables: docs already transferred to wiki

2 files changed, 0 insertions, 397 deletions

diff --git a/plugins/Variables/docs/copying.txt b/plugins/Variables/docs/copying.txt
deleted file mode 100644
index bd5cace35b..0000000000
--- a/plugins/Variables/docs/copying.txt
+++ /dev/null
@@ -1 +0,0 @@
-this is not meant to be distributed in any way. WIP.
\ No newline at end of file
diff --git a/plugins/Variables/docs/readme.txt b/plugins/Variables/docs/readme.txt
deleted file mode 100644
index af25cbf0fa..0000000000
--- a/plugins/Variables/docs/readme.txt
+++ /dev/null
@@ -1,396 +0,0 @@
-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(<ICQ:12345678>,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 <PROTOCOL:UNQIUEID>, 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 <PROTOID:UNIQUEID>, for example

-   <MSN:miranda@hotmail.com> or <ICQ:123456789>.

-

--  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.