UserInfoEx, Variables: changed folder structure

git-svn-id: http://svn.miranda-ng.org/main/trunk@1160 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c

3 files changed, 449 insertions, 0 deletions

diff --git a/plugins/Variables/docs/Variables.txt b/plugins/Variables/docs/Variables.txt
new file mode 100644
index 0000000000..14b37e0a48
--- /dev/null
+++ b/plugins/Variables/docs/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(<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)

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

diff --git a/plugins/Variables/docs/copying.txt b/plugins/Variables/docs/copying.txt
new file mode 100644
index 0000000000..bd5cace35b
--- /dev/null
+++ b/plugins/Variables/docs/copying.txt
@@ -0,0 +1 @@
+this is not meant to be distributed in any way. WIP.
\ No newline at end of file
diff --git a/plugins/Variables/docs/variables-translation.txt b/plugins/Variables/docs/variables-translation.txt
new file mode 100644
index 0000000000..2b8ef53a7e
--- /dev/null
+++ b/plugins/Variables/docs/variables-translation.txt
@@ -0,0 +1,45 @@
+; Common strings that belong to many files

+;[Description]

+;[Help]

+;[Variables]

+

+; ../../plugins/Variables/Variables.rc

+;[Auto parse]

+;[Automatically strip \"end of line\" characters]

+;[Automatically strip all non-parsing characters]

+;[Automatically strip white space]

+;[Click on the help button to get more information]

+;[Close]

+;[Don't set a contact]

+;[Notes]

+;[OK]

+;[Parse]

+;[Parse options]

+;[Parse the following string at startup]

+;[Please enter your input below]

+;[Set to the following contact]

+;[Setting]

+;[Tab1]

+;[Test area]

+;[The Variables plugin translates various tokens into a certain value. An example is: I'm running Miranda %mirandaversion%. The substring %mirandaversion% will be translated into the correct version number. The following list shows all available tokens.]

+;[The token %extratext% is translated into a string which depends on the situation in which the string is parsed. Use this dialog to simulate the string to which %extratext% translates.]

+;[The token %subject% is translated into a special contact, which depends on the situation in which the string is parsed. Use this dialog to simulate the contact to which %subject% translates. An example for using this token is: !cinfo(%subject%,display).]

+;[Trigger when the following string changes]

+;[Variables...]

+

+; ../../plugins/Variables/help.cpp

+;[%extratext%]

+;[%subject%]

+;[Cancel]

+;[Input]

+;[Open String Formatting Help]

+;[Token]

+;[Tokens]

+;[Variables Help]

+

+; ../../plugins/Variables/options.cpp

+;[Services]

+

+; ../../plugins/Variables/parse_external.cpp

+;[Paused]

+;[Stopped]