Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

<languages/>{{PluginCard}}
Adds support for dynamic variables in strings for plugins.

This plugin is a service plugin other plugins can use it to format a string which contains variables. Variables can be used to show the currently playing song in Winamp, the last message you received, the status of a certain contact and much more. The Variables plugin allows you to use special formatting strings within plugins that process their strings using this plugin. Examples of such plugins are {{Plugin|Tipper}} and {{Plugin|StatusManager}}.

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

== Usage ==

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 {{While|tpl=Plugin|NewAwaySys|Tipper|SimpleStatusMsg|StatusManager}}. 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 {{Plugin|NewAwaySys}}) supports the Variables plugin, you can enter a text like the following to show your current Winamp song in your away message:

<pre style="overflow:auto;">
Hi, I'm listening to %winampsong%.
</pre>
In this example, the token '%winampsong%' will be translated by the Variables plugin into the current song. Please see [[#Notes|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. 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 {{Menu|Services|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:
<pre style="overflow:auto;">
Message waiting: !message(,first,rcvd,unread)
</pre>
In case you use
<pre style="overflow:auto;">
?message(,first,rcvd,unread)
</pre>
and the message would be
<pre style="overflow:auto;">
You should use the string %winampsong% to get the song.
</pre>
the result could be
<pre style="overflow:auto;">
Message waiting: You should use the string DJ Mike Llama - Llama Whippin' Intro to get the song.
</pre>

=== `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:
<pre style="overflow:auto;">
Use `%miranda_path%` to show the installation path.
</pre>
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 <nowiki>#</nowiki> character to the end of the line will be removed. Example:
<pre style="overflow:auto;">
%dbprofile% #this is a useless comment.
</pre>

The Variables plugin allows you to build much more complex formatting strings than the one shown above. Please refer to the [[#Additional help|Additional help]] and [[#Notes|Notes]] sections 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 space
: 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 create aliases using the alias function.
;Auto parse
: Normally the string is only parsed when you press the {{Button|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:
<pre style="overflow:auto;">
!if(%winampsong%,`winamp is running`,`winamp is not running`)
</pre>

=== cinfo(x,y) ===

* x specifies the contact (see [[#Notes|Notes]]).
* y specifies the info you want to retrieve, the following values are possible:
<pre style="overflow:auto;">
first, last, nick, cnick, email, city, state, country, phone, homepage, about, gender, age, firstlast, id, display,
protocol, status, intip, extip, protoid, fax, cellular, timezone, mynotes, bday, bmonth, byear, street, zip, lang1,
lang2, lang3, coname, codept, copos, costreet, cocity, costate, cozip, cocountry, cohomepage
</pre>

Example:
<pre style="overflow:auto;">
!cinfo(<ICQ:12345678>,nick)
</pre>

=== lsdate(x,y), lstime(x,y), lsstatus(x) ===

These functions require {{Plugin|SeenPlugin|LastSeen}} to be installed.
<pre style="overflow:auto;">
lsdate(x,y), cdate(x)
</pre>

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.

{{TNT|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'.
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:
<pre style="overflow:auto;">
!alias(song(pl,st,pa,nr),!switch(?if(!and(%winampstate%,%winampsong%),%winampstate%,`Not Running`),`Playing`,pl,`Paused`,pa,`Stopped`,st,`Not Running`,nr))
</pre>

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:
<pre style="overflow:auto;">
?song(%winampsong%` is playing`,`just stopped listening to `%winampsong%,%winampsong%` <- paused`,`Winamp is not running`)
</pre>

=== 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:
<pre style="overflow:auto;">
!message(,`first`,`rcvd`,`unread`)
</pre>
This is 'normal' operation, to get the first message in the message queue.

<pre style="overflow:auto;">
!message(%subject%,`last`,`rcvd`,`unread`)
</pre>
Get the last message you received from the contact %subject%, which is in the message queue.

<pre style="overflow:auto;">
!message(%subject%,`last`,,)
</pre>
Get the last message from contact %subject%. This one could be sent, received, read or unread.

<pre style="overflow:auto;">
!message(,,,)
</pre>
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:
<pre style="overflow:auto;">
!for(!puts(i,0),!not(!strcmp(!get(i),3)),!puts(i,!add(!get(i),1)),i=!get(i)!crlf())
</pre>

== Notes ==
# Whenever a function requires a contact as an argument, you can specify it in two ways:
#* Using a unique ID (UIN for ICQ, JID for Jabber) or, a protocol ID followed by a unique ID in the form <PROTOID:UNIQUEID>, for example <JABBER:miranda@example.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:<pre style="overflow:auto;">first, last, nick, email, id, display</pre>Example:<pre style="overflow:auto;">?contact(miranda@example.com,email)</pre>or<pre style="overflow:auto;">?contact(Miranda,nick).</pre>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"<pre style="overflow:auto;">!puts(count,!ccount(`Marley`,display))</pre>loop through these contacts, for each of them, show the e-mail address<pre style="overflow:auto;">!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))</pre>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.
# The %winampsong% field will only retrieve a song for Winamp, for Foobar2000, I recommend using foo_text and the txtfile function.
# Variables syntax is inspired by the TAGZ system used in [https://www.foobar2000.org/ Foobar2000].

Export translations

Navigation menu

Search