Plugin:Variables/ru: Difference between revisions

From Miranda NG
Plugin:Variables/ru
Jump to navigation Jump to search
(модуль -> плагин)
(Updating to match new version of source page)
 
(19 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{PluginCard
<languages/>{{PluginCard}}
| name=Variables
| authors={{while|tpl=Developer|P. Boon|Ricardo Pescuma|George Hazan}}
| screenshot=
| dll=Variables.dll
}}{{Languages}}
Поддержка динамических переменных для других плагинов.
Поддержка динамических переменных для других плагинов.
Эти переменные могут использоваться для отображения текущей песни в винампе, последнего полученного сообщения, статуса определённого контакта и многого другого. Плагин позволяет вам использовать специально отформатированные строки в других плагинах, которые обрабатывают свои строки при помощи этого. Примерами таких плагинов являются {{Plugin|Tipper}} и {{Plugin|StatusManager}}.
== О плагине ==
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.
== Использование ==
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:<!--
--><p>'''contact(x,y)'''</p><!--
--><p>A contact will be searched which will have value x for its property y, y can be one of the following:</p><!--
--><p><pre style="overflow:auto;">first, last, nick, email, id, display</pre></p><!--
--><p>Example:</p><!--
--><p><pre style="overflow:auto;">?contact(miranda@example.com,email)</pre></p><!--
--><p>or</p><!--
--><p><pre style="overflow:auto;">?contact(Miranda,nick).</pre></p><!--
--><p>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.</p><!--
--><p>Example:</p><!--
--><p>get the number of contacts with the display name "Marley"</p><!--
--><p><pre style="overflow:auto;">!puts(count,!ccount(`Marley`,display))</pre></p><!--
--><p>loop through these contacts, for each of them, show the e-mail address</p><!--
--><p><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></p><!--
--><p>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.</p>
# The %winampsong% field will only retrieve a song for Winamp, for Foobar2000, I recommend using foo_text<!-- ([http://members.lycos.co.uk/musicf/ download]) — the link is dead --> and the txtfile function.
# Variables syntax is inspired by the TAGZ system used in [https://www.foobar2000.org/ Foobar2000].
{{PluginGroups}}

Latest revision as of 21:16, 12 February 2022

Other languages:
Variables
Нет изображения
Имя файла Variables.dll
Авторы P. Boon, Ricardo Pescuma, George Hazan
Скачать
Стабильная версия: 32-bit, 64-bit
Версия в разработке: 32-bit, 64-bit

Поддержка динамических переменных для других плагинов.

Эти переменные могут использоваться для отображения текущей песни в винампе, последнего полученного сообщения, статуса определённого контакта и многого другого. Плагин позволяет вам использовать специально отформатированные строки в других плагинах, которые обрабатывают свои строки при помощи этого. Примерами таких плагинов являются Tipper и StatusManager.

О плагине

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.

Использование

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, 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 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 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 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:

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 `%miranda_path%` 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 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 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, 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 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.

Примечание
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:

!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 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:

      first, last, nick, email, id, display

      Example:

      ?contact(miranda@example.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 and the txtfile function.
  3. Variables syntax is inspired by the TAGZ system used in Foobar2000.