Difference between revisions of "Ru:Introduction to SourcePawn"

From AlliedModders Wiki
Jump to: navigation, search
(Объявлены)
 
(57 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].
 
Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].
  
Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins|Введение в SourceMod плагины]], для введения в SourceMod API.
+
Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.
  
 
=Введение для новичков=
 
=Введение для новичков=
Line 22: Line 22:
  
 
В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
 
В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Числовые (могут содержать только произвольные числовые данные), как показано выше.
+
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Строковые (могут содержать целый ряд текстовых символов)
+
*Многострочные (могут содержать целый ряд текстовых символов)
  
 
==Функции==
 
==Функции==
Line 56: Line 56:
  
  
=Особенности Павна=
+
=Особенности языка=
Павн может показатся очень похожим на другие языки программирования, например Си, но павн от них фундаментально отличается.Не столь важно, чтобы вы сейчас же поняли его отличия, но они понадобятся, если вы уже знаете один из языков программирования.
+
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Павн имеет только 2 вида информации''' У павна есть 2 видa информации - ЯЧЕЙКА и СТРОКА (Cell , String)Детали будут пожже.
+
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
 +
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
 +
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
 +
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Python и Ruby.
 +
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.   
 +
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.
  
*'''Павн не мусорит''' Павн, как язык, не выделят память под действия, и потому он не мусорит (Утечки памяти aka Memory Leaks).  Если функция выделит память, то вы несете ответственность за ее освобождение.
+
Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.
*'''Павн не обектно-ориентированный язык''' Павн является процедурным, и полагается на подпрограммы.  Также у него нету Си-подобных структур.
 
*'''Павн не функционален.''' Павн является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
 
*'''Павн однопоточный''' As of this writing, Pawn is not thread safe. 
 
*'''Павн не интерпритируемый''' Нууу, почти.  Он интерпритируется на очень низком уровне.  Вы должны скомпилировать код, из которого получится бинарный файл (екзешка, ехе, программа).  Ета программа будет работать на той платформе, которую использует хост.  Ето ускоряет загрузку и позволяет находить ошибки легче.
 
 
 
Етот язык был сделан ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом программы очень маленькие в размере и очень быстрые.
 
  
 
=Переменные=
 
=Переменные=
В Pawn есть всего два типа переменных: '''cell''' и '''String'''. cell может содержать 32 бита цифровых данных. String последовательный список из UTF-8 символов.
+
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.
  
'''cell''' не имеет своего типа, однако они могут быть '''Маркированы'''(tagged). Тег позволяет вам указывать,где определенную ячейку можно использовать.  Типичные теги:
+
'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать.  Типичные теги:
 
*(пусто), или '''_''' - Нет тега.  Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
 
*(пусто), или '''_''' - Нет тега.  Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой(небольших).
+
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения  значений '''true'''(истина) или '''false'''(ложь).
+
*'''bool''' - используют для хранения  значений '''true''' (истина) или '''false''' (ложь).
  
Со строками все по другому, они будут рассмотрены в другом блоке.  
+
Со строками все по другому, они будут рассмотрены далее.
  
==Объявления ==
+
==Объявления==
 
Примеры разных правильных объявлений переменных.
 
Примеры разных правильных объявлений переменных.
 
<pawn>
 
<pawn>
Line 89: Line 88:
 
Неправильные объявления переменных
 
Неправильные объявления переменных
 
<pawn>
 
<pawn>
new a = 5.0;        //Несоответствие тегов. 5.0 с тегом Float
+
new a = 5.0;        //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5;    //Несоответствие тегов. 5 без тега.
+
new Float:b = 5;    //Несоответствие тегов. 5 без тега.
 
</pawn>
 
</pawn>
  
Line 101: Line 100:
  
 
==Присвоение==
 
==Присвоение==
Переменные могут быть присвоены данные после создания. Пример:
+
Переменным могут быть присвоены данные после создания. Пример:
 
<pawn>new a, Float:b, bool:c;
 
<pawn>new a, Float:b, bool:c;
  
Line 109: Line 108:
 
</pawn>
 
</pawn>
  
=Arrays=
+
=Массивы=
An array is a sequence of data in a sequential list. Arrays are useful for storing multiple pieces of data in one variable, and often greatly simplify many tasks.
+
Массив это последовательность данных в последовательном списке. Массивы очень полезны для хранения нескольких единиц данных в одной переменной, а зачастую могут значительно упростить многие задачи.
  
==Declaration==
+
==Описание==
An array is declared using brackets. Some examples of arrays:
+
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
 
<pawn>
 
<pawn>
new players[32];    //Stores 32 cells (numbers)
+
new players[32];    //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Stores 3 floating point numbers
+
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
 
</pawn>
 
</pawn>
  
By default, arrays are initialized to 0. You can assign them different default values, however:
+
По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
 
<pawn>
 
<pawn>
new numbers[5] = {1, 2, 3, 4, 5};      //Stores 1, 2, 3, 4, 5 in the cells.
+
new numbers[5] = {1, 2, 3, 4, 5};      //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0};  //Stores 1.0, 2.0, 3.0 in the cells.
+
new Float:origin[3] = {1.0, 2.0, 3.0};  //Набор 1.0, 2.0, 3.0 из однострочных данных.
 
</pawn>
 
</pawn>
  
You can leave out the array size if you're going to pre-assign data to it. For example:
+
Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
 
<pawn>
 
<pawn>
 
new numbers[] = {1, 3, 5, 7, 9};
 
new numbers[] = {1, 3, 5, 7, 9};
 
</pawn>
 
</pawn>
  
The compiler will automatically deduce that you intended an array of size 5.
+
Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.
  
==Usage==
+
==Использование==
Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.
+
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.
  
For example, here is an example of the above code using indexes:
+
Вот пример кода с использованием индексов:
 
<pawn>
 
<pawn>
 
new numbers[5], Float:origin[3];
 
new numbers[5], Float:origin[3];
Line 149: Line 148:
 
</pawn>
 
</pawn>
  
Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.
+
Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.
  
To use an incorrect index will cause an error. For example:
+
Использование неверного индекса вызовет ошибку. Например:
 
<pawn>
 
<pawn>
 
new numbers[5];
 
new numbers[5];
Line 157: Line 156:
 
numbers[5] = 20;</pawn>
 
numbers[5] = 20;</pawn>
  
This may look correct, but 5 is not a valid index. The highest valid index is 4.
+
Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.
  
You can use any expression as an index. For example:
+
Вы можете использовать любые выражения, как индекс. Например:
 
<pawn>new a, numbers[5];
 
<pawn>new a, numbers[5];
  
a = 1;                  //Set a = 1
+
a = 1;                  //Сделает a = 1
numbers[a] = 4;          //Set numbers[1] = 4
+
numbers[a] = 4;          //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Set numbers[4] = 2
+
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
 
</pawn>
 
</pawn>
  
Expressions will be discussed in depth later in the article.
+
Выражения будут обсуждаться подробнее в конце статьи.
  
=Strings=
+
=Строки=
Strings are a convenient method of storing text. The characters are stored in an array. The string is terminated by a '''null terminator''', or a 0. Without a null terminator, Pawn would not know where to stop reading the string. All strings are UTF-8 in SourcePawn.
+
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.
  
Notice that Strings are a combination of arrays and cells. Unlike other languages, this means you must know how much space a string will use in advance. That is, strings are not dynamic. They can only grow to the space you allocate for them.
+
Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.
  
''Note for experts: They're not actually cells. SourcePawn uses 8-bit storage for String arrays as an optimization. This is what makes String a type and not a tag.''
+
''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''
  
==Usage==
+
==Использование==
Strings are declared almost equivalently to arrays. For example:
+
Строки были созданы почти в равной степени и для массивов. Например:
 
<pawn>
 
<pawn>
 
new String:message[] = "Hello!";
 
new String:message[] = "Hello!";
Line 183: Line 182:
 
</pawn>
 
</pawn>
  
These are equivalent to doing:
+
Это равносильно следующему:
 
<pawn>
 
<pawn>
 
new String:message[7], String:clams[6];
 
new String:message[7], String:clams[6];
Line 202: Line 201:
 
</pawn>
 
</pawn>
  
Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.
+
Хотя строки редко инициализируют таким образом, очень важно помнить о концепции нулевого символа, который свидетельствует о конце строки. Компилятор и большинство SourceMod функций будут автоматически остановлены нулевым символом, поэтому он является очень важным, при манипулировании строками напрямую.
  
Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.
+
Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.
  
==Characters==
+
==Символы==
A character of text can be used in either a String or a cell. For example:
+
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
 
<pawn>new String:text[] = "Crab";
 
<pawn>new String:text[] = "Crab";
 
new clam;
 
new clam;
  
clam = 'D';        //Set clam to 'D'
+
clam = 'D';        //Устанавливает однострочной переменной значение 'D'
text[0] = 'A';      //Change the 'C' to 'A', it is now 'Arab'
+
text[0] = 'A';      //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0];    //Set clam to 'A'
+
clam = text[0];    //Устанавливает однострочной переменной значение 'A'
text[1] = clam;    //Change the 'r' to 'A', is is now 'AAab'
+
text[1] = clam;    //Меняет 'r' на 'A', сейчас получилось 'AAab'
 
</pawn>
 
</pawn>
  
What you can't do is mix character arrays with strings. The internal storage is different. For example:
+
То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
 
<pawn>
 
<pawn>
new clams[] = "Clams";                      //Invalid, needs String: type
+
new clams[] = "Clams";                      //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0};  //Valid, but NOT A STRING.
+
new clams[] = {'C', 'l', 'a', 'm', 's', 0};  //Верно, но это НЕ СТРОКА.
 
</pawn>
 
</pawn>
  
 +
=Функции=
 +
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.
  
=Functions=
+
Существуют два типа вызова функции:
Functions, as stated before, are isolated blocks of code that perform an action.  They can be invoked, or '''called''', with '''parameters''' that give specific options.
+
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
 +
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).
  
There are two types of ways functions are called:
+
Существуют шесть видов функций:
*'''direct call''' - You specifically call a function in your code.
+
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''callback''' - The application calls a function in your code, as if it were an event trigger.
+
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
 +
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
 +
*'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.
 +
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
 +
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.
  
There are five types of functions:
+
Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.
*'''native''': A direct, internal function provided by the application.
 
*'''public''': A callback function that is visible to the application and other scripts.
 
*'''normal''': A normal function that only you can call.
 
*'''stock''': A normal function provided by an include file.  If unused, it won't be compiled.
 
*'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.
 
  
All code in Pawn must exist in functions.  This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.
+
==Описание==
 +
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.
  
==Declaration==
+
Пример функции:
Unlike variables, functions do not need to be declared before you use them.  Functions have two pieces, the '''prototype''' and the '''body'''.  The prototype contains the name of your function and the parameters it will accept.  The body is the contents of its code.
 
 
 
Example of a function:
 
 
<pawn>
 
<pawn>
 
AddTwoNumbers(first, second)
 
AddTwoNumbers(first, second)
Line 252: Line 251:
 
}</pawn>
 
}</pawn>
  
This is a simple function. The prototype is this line:
+
Это простая функция. Модель этой строки:
 
<pawn>AddTwoNumbers(first, second)</pawn>
 
<pawn>AddTwoNumbers(first, second)</pawn>
  
Broken down, it means:
+
Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Name of the function.
+
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Name of the first parameter, which is a simple cell.
+
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Name of the second parameter, which is a simple cell.
+
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.
  
The body is a simple block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions ''return a cell'' upon completion. That means, for example:
+
Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:
  
 
<pawn>new sum = AddTwoNumbers(4, 5);</pawn>
 
<pawn>new sum = AddTwoNumbers(4, 5);</pawn>
  
The above code will assign the number 9 to sum. The function adds the two inputs, and the sum is given as the '''return value'''. If a function has no return statement or does not place a value in the return statement, it returns 0 by default.
+
Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.
  
A function can accept any type of input. It can return any cell, but not arrays or strings. Example:
+
Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
 
<pawn>Float:AddTwoFloats(Float:a, Float:b)
 
<pawn>Float:AddTwoFloats(Float:a, Float:b)
 
{
 
{
Line 274: Line 273:
 
}</pawn>
 
}</pawn>
  
''Note that if in the above function, you returned a non-Float, you would get a tag mismatch.''
+
''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''
  
You can, of course, pass variables to functions:
+
Можно, конечно, передавать переменные в функции:
 
<pawn>new numbers[3] = {1, 2, 0};
 
<pawn>new numbers[3] = {1, 2, 0};
  
 
numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>
 
numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>
  
Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:
+
Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
 
<pawn>new a = 5;
 
<pawn>new a = 5;
  
Line 291: Line 290:
 
}</pawn>
 
}</pawn>
  
This code would not change the value of <tt>a</tt>. That is because a copy of the value in <tt>a</tt> is passed instead of <tt>a</tt> itself.
+
Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.
  
More examples of functions will be provided throughout the article.
+
Больше примеров функций будут демонстрироваться и в других частях статьи.
  
 
==Publics==
 
==Publics==
Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from <tt>sourcemod.inc</tt>:
+
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:
  
 
<pawn>forward OnPluginStart();
 
<pawn>forward OnPluginStart();
 
forward OnClientDisconnected(client);</pawn>
 
forward OnClientDisconnected(client);</pawn>
  
To implement and receive these two events, you would write functions as such:
+
Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:
  
 
<pawn>public OnPluginStart()
 
<pawn>public OnPluginStart()
 
{
 
{
   /* Code here */
+
   /* Код здесь */
 
}
 
}
  
 
public OnClientDisconnected(client)
 
public OnClientDisconnected(client)
 
{
 
{
   /* Code here */
+
   /* Код здесь */
 
}</pawn>
 
}</pawn>
  
The '''public''' keyword exposes the function publicly, and allows the parent application to directly call the function.
+
Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.
  
 
==Natives==
 
==Natives==
Natives are builtin functions provided by the application. You can call them as if they were a normal function. For example, SourceMod has the following function:
+
Natives имеют встроенные функции, предоставляемые SourceMod. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:
  
 
<pawn>native FloatRound(Float:num);</pawn>
 
<pawn>native FloatRound(Float:num);</pawn>
  
It can be called like so:
+
Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2);    //Results in num = 5</pawn>
+
<pawn>new num = FloatRound(5.2);    //Результат в num = 5</pawn>
  
==Array Parameters==
+
==Параметры массива==
You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.
+
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.
  
 
<pawn>
 
<pawn>
Line 336: Line 335:
 
}</pawn>
 
}</pawn>
  
The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:
+
Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
 
<pawn>example[2] = 29;</pawn>
 
<pawn>example[2] = 29;</pawn>
  
This is only possible because the array can be directly modified. To prevent an array from being modified, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:
+
Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:
  
 
<pawn>CantChangeArray(const array[], index, value)
 
<pawn>CantChangeArray(const array[], index, value)
 
{
 
{
   array[index] = value;    //Won't compile
+
   array[index] = value;    //Не компилируется
 
}</pawn>
 
}</pawn>
  
It is a good idea to use <tt>const</tt> in array parameters if you know the array won't be modified; this can prevent coding mistakes.
+
Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.
  
=Expressions=
+
=Выражения=
Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict "order of operations."  They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.
+
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.
  
The simplest expression is a single number.  For example:
+
Приведем пример простейшего выражения:
 
<pawn>
 
<pawn>
0;  //Returns the number 0
+
0;  //Возвращает число 0
(0); //Returns the number 0 as well
+
(0); //Так же возвращает число 0
 
</pawn>
 
</pawn>
  
Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.
+
Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.
  
The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:
+
Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
 
<pawn>
 
<pawn>
5 + 6;                  //Evaluates to 11
+
5 + 6;                  //Вычисляет как 11
5 * 6 + 3;              //Evaluates to 33
+
5 * 6 + 3;              //Вычисляет как 33
5 * (6 + 3);            //Evaluates to 45
+
5 * (6 + 3);            //Вычисляет как 45
5.0 + 2.3;              //Evaluates to 7.3
+
5.0 + 2.3;              //Вычисляет как 7.3
(5 * 6) % 7;            //Modulo operator, evaluates to 2
+
(5 * 6) % 7;            //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9;    //Evaluates to 7
+
(5 + 3) / 2 * 4 - 9;    //Вычисляет как 7
 
</pawn>
 
</pawn>
  
As noted, expressions can contain variables, or even functions:
+
Как уже отмечалось, выражения могут содержать переменные, или даже функции:
 
<pawn>
 
<pawn>
 
new a = 5 * 6;
 
new a = 5 * 6;
new b = a * 3;      //Evaluates to 90
+
new b = a * 3;      //Вычисляет как 90
 
new c = AddTwoNumbers(a, b) + (a * b);
 
new c = AddTwoNumbers(a, b) + (a * b);
 
</pawn>
 
</pawn>
  
==Operators==
+
Примечание:  String manipulation routines may be found in the string.inc file located in the include subdirectory.  They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.
There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:
+
 
 +
==Операторы==
 +
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
 
<pawn>new a = 5;
 
<pawn>new a = 5;
  
 
a = a + 5;</pawn>
 
a = a + 5;</pawn>
  
Can be rewritten as:
+
Может быть переписан, как:
 
<pawn>new a = 5;
 
<pawn>new a = 5;
 
a += 5;</pawn>
 
a += 5;</pawn>
  
This is true of the following operators in Pawn:
+
Это верно в отношении следующих операторов в Pawn:
 
*Four-function: *, /, -, +
 
*Four-function: *, /, -, +
 
*Bit-wise: |, &, ^, ~, <<, >>
 
*Bit-wise: |, &, ^, ~, <<, >>
  
Additionally, there are increment/decrement operators:
+
Кроме того, существуют инкремент/декремент операторы:
 
<pawn>a = a + 1;
 
<pawn>a = a + 1;
 
a = a - 1;</pawn>
 
a = a - 1;</pawn>
  
Can be simplified as:
+
Может быть упрощено, как:
 
<pawn>a++;
 
<pawn>a++;
 
a--;</pawn>
 
a--;</pawn>
  
As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.
+
Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.
  
* ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.
+
* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.
+
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.
  
In other words, <tt>a++</tt> evaluates to the value of <tt>a</tt> while <tt>++a</tt> evaluates to the value of <tt>a + 1</tt>. In both cases <tt>a</tt> is incremented by <tt>1</tt>.
+
Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.
  
For example:
+
Например:
  
 
<pawn>new a = 5;
 
<pawn>new a = 5;
Line 412: Line 413:
 
</pawn>
 
</pawn>
  
In (1) <tt>b</tt> is assigned <tt>a</tt>'s ''old'' value ''before'' it is incremented to <tt>6</tt>, but in (2) <tt>c</tt> is assigned <tt>a</tt>'s ''new'' value ''after'' it is incremented to <tt>7</tt>.
+
(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.
  
==Comparison Operators==
+
==Операторы сравнения==
There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):
+
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - True if a and b have the same value.
+
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - True if a and b have different values.
+
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a &gt; b</tt> - True if a is greater than b
+
*<tt>a &gt; b</tt> - Действительно, если оно больше b
*<tt>a &gt;= b</tt> - True if a is greater than or equal to b
+
*<tt>a &gt;= b</tt> - Действительно, если оно больше или равно b
*<tt>a &lt; b</tt> - True if a is less than b
+
*<tt>a &lt; b</tt> - Действительно, если оно меньше b
*<tt>a &lt;= b</tt> - True if a is less than or equal to b
+
*<tt>a &lt;= b</tt> - Действительно, если оно меньше или равно b
  
For example:
+
Например:
 
<pawn>
 
<pawn>
(1 != 3);        //Evaluates to true because 1 is not equal to 3.
+
(1 != 3);        //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6);    //Evaluates to true because 3+3 is 6.
+
(3 + 3 == 6);    //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4);    //Evaluates to false because 3 is less than 4.
+
(5 - 2 >= 4);    //Определяется как ложь, поскольку 3 меньше 4.
 
</pawn>
 
</pawn>
  
Note that these operators do not work on arrays or strings. That is, you cannot compare either using <tt>==</tt>.
+
Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.
  
==Truth Operators==
+
==Действительные операторы==
These truth values can be combined using three boolean operators:
+
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - True if both a and b are true. False if a or b (or both) is false.
+
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
! <tt>&&</tt> !! 0 !! 1
 
! <tt>&&</tt> !! 0 !! 1
Line 444: Line 445:
 
| 0 || 1
 
| 0 || 1
 
|}
 
|}
*<tt>a || b</tt> - True if a or b (or both) is true. False if both a and b are false.
+
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
 
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
Line 454: Line 455:
 
| 1 || 1
 
| 1 || 1
 
|}
 
|}
*<tt>!a</tt> - True if a is false. False if a is true.
+
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
{| border="1" cellpadding="2" cellspacing="0" align="center"
 
! <tt>!</tt> !! 0 !! 1
 
! <tt>!</tt> !! 0 !! 1
Line 462: Line 463:
 
|}
 
|}
  
For example:
+
Например:
 
<pawn>
 
<pawn>
(1 || 0);        //Evaluates to true because the expression 1 is true
+
(1 || 0);        //Определяется как истина, так как выражение 1 истинное
(1 && 0);        //Evaluates to false because the expression 0 is false
+
(1 && 0);        //Определяется как ложь, так как выражение 0 ложное
(!1 || 0);        //Evaluates to false because !1 is false.
+
(!1 || 0);        //Определяется как ложь, так как выражение !1 ложное.
 
</pawn>
 
</pawn>
  
==Left/Right Values==
+
==Левое/правое значения==
Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.
+
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.
  
For example:
+
Например:
 
<pawn>
 
<pawn>
 
new a = 5;</pawn>
 
new a = 5;</pawn>
  
In this example <tt>a</tt> is an l-value and <tt>5</tt> is an r-value.
+
В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.
  
The rules:
+
Правила:
*'''Expressions are never l-values'''.
+
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Variables are both l-values and r-values'''.
+
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.
  
=Conditionals=
+
=Условия=
Conditional statements let you only run code if a certain condition is matched.
+
Условия позволяют Вам запускать код, определенное условие выполнено.
  
==If Statements==
+
==Если соответствует==
If statements test one or more conditions. For example:
+
Если соответствует одно или более условий. Например:
  
 
<pawn>
 
<pawn>
 
if (a == 5)
 
if (a == 5)
 
{
 
{
   /* Code that will run if the expression was true */
+
   /* Код будет запущен, если условие будет истинным */
 
}</pawn>
 
}</pawn>
  
They can be extended to handle more cases as well:
+
Они могут быть расширены для более сложных случаев:
 
<pawn>
 
<pawn>
 
if (a == 5)
 
if (a == 5)
 
{
 
{
   /* Code */
+
   /* Код */
 
}
 
}
 
else if (a == 6)
 
else if (a == 6)
 
{
 
{
   /* Code  */
+
   /* Код */
 
}
 
}
 
else if (a == 7)
 
else if (a == 7)
 
{
 
{
   /* Code */
+
   /* Код */
 
}</pawn>
 
}</pawn>
  
You can also handle the case of no expression being matched. For example:
+
Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
 
<pawn>
 
<pawn>
 
if (a == 5)
 
if (a == 5)
 
{
 
{
   /* Code */
+
   /* Код */
 
}
 
}
 
else
 
else
 
{
 
{
   /* Code that will run if no expressions were true */
+
   /* Код, который будет запущен если нет истинного выражения */
 
}</pawn>
 
}</pawn>
  
==Switch Statements==
+
==Оператор выбора==
Switch statements are restricted if statements. They test one expression for a series of possible values. For example:
+
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:
  
 
<pawn>
 
<pawn>
Line 528: Line 529:
 
   case 5:
 
   case 5:
 
   {
 
   {
       /* code */
+
       /* Код */
 
   }
 
   }
 
   case 6:
 
   case 6:
 
   {
 
   {
       /* code */
+
       /* Код */
 
   }
 
   }
 
   case 7:
 
   case 7:
 
   {
 
   {
       /* code */
+
       /* Код */
 
   }
 
   }
 
   case 8, 9, 10:
 
   case 8, 9, 10:
 
   {
 
   {
       /* Code */
+
       /* Код */
 
   }
 
   }
 
   default:
 
   default:
 
   {
 
   {
       /* will run if no case matched */
+
       /* будет запущен, если не одно условие не соответствует */
 
   }
 
   }
 
}</pawn>
 
}</pawn>
  
Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.
+
В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.
  
=Loops=
+
=Циклы=
Loops allow you to conveniently repeat a block of code while a given condition remains true.
+
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.
  
==For Loops==
+
==For циклы==
For loops are loops which have four parts:
+
For циклы, это циклы, которые состоят из четырех частей:
*The '''initialization''' statement - run once before the first loop.
+
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.
+
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*The '''iteration''' statement - run after each loop.
+
*Оператор '''итерации''' - запускается после каждого цикла.
*The '''body''' block - run each time the '''condition''' statement evaluates to true.
+
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.
  
 
<pawn>
 
<pawn>
for ( /* initialization */ ; /* condition */ ; /* iteration */ )
+
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
 
{
 
{
   /* body */
+
   /* тело */
 
}
 
}
 
</pawn>
 
</pawn>
  
A simple example is a function to sum an array:
+
Простым примером является функция сложения массива:
 
<pawn>
 
<pawn>
 
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
 
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
Line 584: Line 585:
 
}</pawn>
 
}</pawn>
  
Broken down:
+
По отдельности:
*<tt>new i = 0</tt> - Creates a new variable for the loop, sets it to 0.
+
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Only runs the loop if <tt>i</tt> is less than <tt>count</tt>. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.
+
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Increments <tt>i</tt> by one after each loop. This ensures that the loop doesn't run forever; eventually <tt>i</tt> will become too big and the loop will end.
+
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.
  
Thus, the <tt>SumArray</tt> function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.
+
Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.
  
==While Loops==
+
==While циклы==
While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:
+
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.
+
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*The '''body''' block - run each time through the loop.
+
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.
  
 
<pawn>
 
<pawn>
while ( /* condition */ )
+
while ( /* условие */ )
 
{
 
{
   /* body */
+
   /* тело */
 
}
 
}
 
</pawn>
 
</pawn>
  
As long as the condition expression remains true, the loop will continue. Every for look can be rewritten as a while loop:
+
До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:
  
 
<pawn>
 
<pawn>
/* initialization */
+
/* инициализация */
while ( /* condition */ )
+
while ( /* условие */ )
 
{
 
{
   /* body */
+
   /* тело */
   /* iteration */
+
   /* итерация */
 
}
 
}
 
</pawn>
 
</pawn>
  
Here is the previous for loop rewritten as a while loop:
+
Вот предыдущий for цикл переписан как while цикл:
 
<pawn>
 
<pawn>
 
SumArray(const array[], count)
 
SumArray(const array[], count)
Line 629: Line 630:
 
}</pawn>
 
}</pawn>
  
There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:
+
Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:
  
 
<pawn>
 
<pawn>
 
do
 
do
 
{
 
{
   /* body */
+
   /* тело */
 
}
 
}
while ( /* condition */ );
+
while ( /* условие */ );
 
</pawn>
 
</pawn>
  
==Loop Control==
+
==Управление циклами==
There are two cases in which you want to selectively control a loop:
+
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''skipping''' one iteration of the loop but continuing as normal, or;
+
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''breaking''' the loop entirely before it's finished.
+
*'''разорвать''' цикл целиком, прежде чем он закончится.
  
Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:
+
Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
 
<pawn>
 
<pawn>
 
/**
 
/**
  * Returns the array index where the value is, or -1 if not found.
+
  * Возвращает массив, если индекс значения, или -1, не найдены.
 
  */
 
  */
 
SearchInArray(const array[], count, value)
 
SearchInArray(const array[], count, value)
Line 665: Line 666:
 
}</pawn>
 
}</pawn>
  
Certainly, this function could simply <tt>return i</tt> instead, but the example shows how <tt>break</tt> will terminate the loop.
+
Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.
 +
 
 +
Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:
  
Similarly, the <tt>continue</tt> keyword skips an iteration of a loop.  For example, let's say we wanted to sum all even numbers:
 
 
<pawn>
 
<pawn>
 
SumEvenNumbers(const array[], count)
 
SumEvenNumbers(const array[], count)
Line 678: Line 680:
 
       if (array[i] % 2 == 1)
 
       if (array[i] % 2 == 1)
 
       {
 
       {
         /* Skip the rest of this loop iteration */
+
         /* Пропускаем оставшуюся часть итерации цикла */
 
         continue;
 
         continue;
 
       }
 
       }
Line 687: Line 689:
 
}</pawn>
 
}</pawn>
  
 
+
=Область действия=
=Scope=
+
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:
 
  
 
<pawn>
 
<pawn>
Line 706: Line 707:
 
}</pawn>
 
}</pawn>
  
In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.
+
В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.
  
Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.
+
Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.
  
Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
+
Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
 
<pawn>
 
<pawn>
 
Function1()
 
Function1()
Line 719: Line 720:
 
}</pawn>
 
}</pawn>
  
In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.
+
В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.
  
This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:
+
Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:
  
 
<pawn>Function1()
 
<pawn>Function1()
Line 733: Line 734:
 
}</pawn>
 
}</pawn>
  
The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
+
Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
 
<pawn>
 
<pawn>
 
Function1()
 
Function1()
Line 747: Line 748:
 
}</pawn>
 
}</pawn>
  
Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.
+
Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.
 
 
  
=Dynamic Arrays=
+
=Динамические массивы=
Dynamic arrays are arrays which don't have a hardcoded size. For example:
+
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:
  
 
<pawn>Function1(size)
 
<pawn>Function1(size)
Line 757: Line 757:
 
   new array[size];
 
   new array[size];
  
   /* Code */
+
   /* Код */
 
}</pawn>
 
}</pawn>
  
Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.
+
Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.
  
Dynamic arrays are only valid at the local scope level, since code cannot exist globally.
+
Динамические массивы, действительны только в локальной области действия, так как код не может существовать на глобальном уровне.
  
=Extended Variable Declarations=
+
=Расширенное объявление переменных=
Variables can be declared in more ways than simply <tt>new</tt>.
+
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.
  
 
==decl==
 
==decl==
===Purpose===
+
===Назначение===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.
+
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.
  
Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.
+
Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.
  
===Explanation===
+
===Объяснение===
For example:
+
Например:
  
 
<pawn>
 
<pawn>
Line 784: Line 784:
 
</pawn>
 
</pawn>
  
In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.
+
В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.
  
Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:
+
Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:
  
 
<pawn>
 
<pawn>
Line 796: Line 796:
 
</pawn>
 
</pawn>
  
===Caveats===
+
===Предостережения===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:
+
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:
  
 
<pawn>
 
<pawn>
Line 809: Line 809:
 
</pawn>
 
</pawn>
  
This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:
+
Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:
  
 
<pawn>
 
<pawn>
Line 819: Line 819:
 
</pawn>
 
</pawn>
  
The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.
+
Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.
  
Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
+
Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
 
<pawn>
 
<pawn>
 
decl String:blah[512];
 
decl String:blah[512];
Line 828: Line 828:
 
</pawn>
 
</pawn>
  
===Golden Rules===
+
===Золотые правила===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
+
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.
+
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.
  
===Notes===
+
===Примечания===
This example is NOT as efficient as a <tt>decl</tt>:
+
Обратите внимание, что <tt>decl</tt> переменную инициализировать явно, но '''ТОЛЬКО''' как строку:
 
<pawn>
 
<pawn>
new String:blah[512] = "a";
+
decl String:blah[512] = "a";
 
</pawn>
 
</pawn>
  
Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.
+
However, any other tag will fail to compile, because the purpose of <tt>decl</tt> is to avoid any initialization:
 +
<pawn>
 +
decl Float:blah[512] = {1.0};
 +
</pawn>
  
Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
+
Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.
 +
 
 +
Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
 
<pawn>decl String:blah[512] = "a";</pawn>
 
<pawn>decl String:blah[512] = "a";</pawn>
  
The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.
+
Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.
 
 
  
 
==static==
 
==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.
+
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.
  
===Global static===
+
===Глобальный static===
A global static variable can only be accessed from within the same file. For example:
+
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:
  
 
<pawn>//file1.inc
 
<pawn>//file1.inc
Line 858: Line 862:
 
static Float:g_value2 = 0.15f;</pawn>
 
static Float:g_value2 = 0.15f;</pawn>
  
If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.
+
Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.
  
===Local static===
+
===Локальный static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:
+
Локальная static переменная является глобальной переменной, которая является видимой лишь из её местной области действия. Например:
  
 
<pawn>
 
<pawn>
Line 873: Line 877:
 
}</pawn>
 
}</pawn>
  
In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.
+
В этом примере, <tt>counter</tt> технически глобальная переменная -- она инициализируется один раз как -1 и никогда не инициализируется заново. Оно не существует в наборе. Это означает, что при каждом запуске функции <tt>MyFunction</tt>, переменная <tt>counter</tt> и ее хранение в памяти одно и тоже.
  
Take this example:
+
Возьмем следающий пример:
 
<pawn>MyFunction(5);
 
<pawn>MyFunction(5);
 
MyFunction(6);
 
MyFunction(6);
 
MyFunction(10);</pawn>
 
MyFunction(10);</pawn>
  
In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.
+
В этом примере, <tt>counter</tt> может быть <tt>-1 +5 +6 +10</tt>, или <tt>20</tt>, поскольку она сохраняется за рамками этой функции. Это может создавать проблемы для рекурсивной функции: если ваша функция может быть рекурсивной, то <tt>static</tt>, как правило, не является хорошей идеей, если только Ваш код не реентерабельный.
  
The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.
+
Преимуществом локальных static переменных является то, что Вам не придется загромождать свой сценарий глобальными переменными. До тех пор, пока переменной не нужно читать другую функцию, Вы можете его пихать внутрь функции и её сохранение будет гарантировано.
  
Note that statics can exist in any local scope:
+
Заметим, что statics может существовать в любой локальной области действия:
  
 
<pawn>
 
<pawn>
Line 897: Line 901:
 
}</pawn>
 
}</pawn>
  
[[Category:SourceMod Scripting]]
+
[[Category:Ru:SourceMod Scripting]]
[[Category:Russian]]
 

Latest revision as of 13:10, 25 June 2011

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. Pawn это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в SourceMod.

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью Ru:Introduction to SourceMod Plugins (Введение в SourceMod плагины), для введения в SourceMod API.

Введение для новичков

Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

Идентификаторы/Ключевые слова

Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, if, for, и return специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

Переменные

Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это переменные. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

new a, b, c, d;
 
a = 5;
b = 16;
c = 0;
d = 500;

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.

  • Однострочные (могут содержать только произвольные числовые данные), как показано выше.
  • Многострочные (могут содержать целый ряд текстовых символов)

Функции

Следующим важным понятием являются функции. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:

функция(<параметры>)

Примеры:

show(56);   //Активирует функцию "show" и присваивает ей число 56
show();     //Активирует функцию "show" без каких-либо данных, пустую
show(a);    //Активирует функцию "show" и присваивает ей переменную с данными

Каждый фрагмент данных передаваемый вызываемой функции, называется параметр. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

Комментарии

Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:

  • // - Двойная косая черта, всё следующие после этой строки игнорируется.
  • /* */ - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

Массивы

Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

{
   here;
   is;
   some;
   code;
}

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.


Особенности языка

Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.

  • Pawn не печатает Pawn имеет только один тип данных - однострочный. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
  • Pawn не собирает мусор Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
  • Pawn не объектно-ориентированный язык Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
  • Pawn не функциональный. Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Python и Ruby.
  • Pawn однопоточный As of this writing, Pawn is not thread safe.
  • Pawn не интерпретируемый Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

Переменные

В Pawn есть всего два типа переменных: однострочные и многострочные. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

однострочные не имеет своего типа, однако они могут быть маркированы(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:

  • (пусто), или _ - Нет тега. Обычно используют для целых чисел (Integers).
  • Float - используют для чисел с плавающей точкой (небольших).
  • bool - используют для хранения значений true (истина) или false (ложь).

Со строками все по другому, они будут рассмотрены далее.

Объявления

Примеры разных правильных объявлений переменных.

new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0;      //Работает, поскольку 0 равно false (ложь)

Неправильные объявления переменных

new a = 5.0;         //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5;     //Несоответствие тегов. 5 без тега.

Если переменная не определена в объявлении то ее значения станет 0

new a;        //значение 0
new Float:b;  //значение 0.0
new bool:c;   //значение false

Присвоение

Переменным могут быть присвоены данные после создания. Пример:

new a, Float:b, bool:c;
 
a = 5;
b = 5.0;
c = true;

Массивы

Массив это последовательность данных в последовательном списке. Массивы очень полезны для хранения нескольких единиц данных в одной переменной, а зачастую могут значительно упростить многие задачи.

Описание

Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:

new players[32];     //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:

new numbers[5] = {1, 2, 3, 4, 5};       //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0};  //Набор 1.0, 2.0, 3.0 из однострочных данных.

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:

new numbers[] = {1, 3, 5, 7, 9};

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

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

Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть индексируемым. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:

new numbers[5], Float:origin[3];
 
numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;

Заметим, что индекс это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:

new numbers[5];
 
numbers[5] = 20;

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:

new a, numbers[5];
 
a = 1;                   //Сделает a = 1
numbers[a] = 4;          //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2

Выражения будут обсуждаться подробнее в конце статьи.

Строки

Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается нулевым символом, или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.

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

Строки были созданы почти в равной степени и для массивов. Например:

new String:message[] = "Hello!";
new String:clams[6] = "Clams";

Это равносильно следующему:

new String:message[7], String:clams[6];
 
message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;

Хотя строки редко инициализируют таким образом, очень важно помнить о концепции нулевого символа, который свидетельствует о конце строки. Компилятор и большинство SourceMod функций будут автоматически остановлены нулевым символом, поэтому он является очень важным, при манипулировании строками напрямую.

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

Символы

Особенность текста может быть использована в любой строке или однострочной переменной. Например:

new String:text[] = "Crab";
new clam;
 
clam = 'D';         //Устанавливает однострочной переменной значение 'D'
text[0] = 'A';      //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0];     //Устанавливает однострочной переменной значение 'A'
text[1] = clam;     //Меняет 'r' на 'A', сейчас получилось 'AAab'

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:

new clams[] = "Clams";                       //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0};  //Верно, но это НЕ СТРОКА.

Функции

Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или вызвоны с параметрами, которые дают особые настройки.

Существуют два типа вызова функции:

  • прямой вызов - Вы специально вызываете функцию в своем коде.
  • обратный вызов - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют шесть видов функций:

  • native: Прямая, внутренняя функция, предусмотренная в приложении.
  • public: Функция обратного вызова, что делает её видимой для приложения и других сценариев.
  • normal: Нормальная функция, которую Вы можете только вызвать.
  • static: The scope of this function is restricted to the current file, can be used in combination with stock.
  • stock: Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
  • forward: Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

Описание

В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, модель и тело. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:

AddTwoNumbers(first, second)
{
  new sum = first + second;
 
  return sum;
}

Это простая функция. Модель этой строки:

AddTwoNumbers(first, second)

Распишем по отдельности:

  • AddTwoNumbers - Название функции.
  • first - Название первого параметра, который представляет собой простой элемент.
  • second - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную sum, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор return, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции возвращают значения после завершения. Это означает, например:

new sum = AddTwoNumbers(4, 5);

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве возвращаемого значения. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:

Float:AddTwoFloats(Float:a, Float:b)
{
   new Float:sum = a + b;
 
   return sum;
}

Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.

Можно, конечно, передавать переменные в функции:

new numbers[3] = {1, 2, 0};
 
numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);

Заметим, что однострочные переменные передаются по значению. То есть, их значение не может быть изменено функцией. Например:

new a = 5;
 
ChangeValue(a);
 
ChangeValue(b)
{
   b = 5;
}

Этот код не будет менять значение a. Это происходит потому, что копия этого значения в a передается вместо a самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

Publics

Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из sourcemod.inc:

forward OnPluginStart();
forward OnClientDisconnected(client);

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

public OnPluginStart()
{
   /* Код здесь */
}
 
public OnClientDisconnected(client)
{
   /* Код здесь */
}

Ключевое слово public делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

Natives

Natives имеют встроенные функции, предоставляемые SourceMod. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

native FloatRound(Float:num);

Её можно вызвать таким образом:

new num = FloatRound(5.2);     //Результат в num = 5

Параметры массива

Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут как ссылка. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

new example[] = {1, 2, 3, 4, 5};
 
ChangeArray(example, 2, 29);
 
ChangeArray(array[], index, value)
{
   array[index] = value;
}

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:

example[2] = 29;

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную const. Это позволит понизить риск на ошибку в коде от её изменения. Например:

CantChangeArray(const array[], index, value)
{
   array[index] = value;    //Не компилируется
}

Это хорошая идея использовать const в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

Выражения

Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:

0;   //Возвращает число 0
(0); //Так же возвращает число 0

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ноль или не ноль. В этом смысле, ноль является ложью (false), а не нулевое значение истиной (true). Например, -1 истина в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:

5 + 6;                   //Вычисляет как 11
5 * 6 + 3;               //Вычисляет как 33
5 * (6 + 3);             //Вычисляет как 45
5.0 + 2.3;               //Вычисляет как 7.3
(5 * 6) % 7;             //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9;     //Вычисляет как 7

Как уже отмечалось, выражения могут содержать переменные, или даже функции:

new a = 5 * 6;
new b = a * 3;      //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);

Примечание: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the API Reference as well.

Операторы

Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:

new a = 5;
 
a = a + 5;

Может быть переписан, как:

new a = 5;
a += 5;

Это верно в отношении следующих операторов в Pawn:

  • Four-function: *, /, -, +
  • Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:

a = a + 1;
a = a - 1;

Может быть упрощено, как:

a++;
a--;

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

  • До: Переменная увеличивается до определения и остальная часть выражения видит новое значение.
  • Пост: Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, a++ определяет значение как a в то время как ++a определяет значение как a + 1. В обоих случаях a увеличивается на 1.

Например:

new a = 5;
new b = a++;   // b = 5, a = 6  (1)
new c = ++a;   // a = 7, c = 7  (2)

(1) b присваивается a со старым значением, до того, как он будет увеличено до 6. (2) c присваивается a с новым значением, после того, как он увеличивается до 7.

Операторы сравнения

Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):

  • a == b - Действительно, если и b имеет то же значение.
  • a != b - Действительно, если b имеет другое значение.
  • a > b - Действительно, если оно больше b
  • a >= b - Действительно, если оно больше или равно b
  • a < b - Действительно, если оно меньше b
  • a <= b - Действительно, если оно меньше или равно b

Например:

(1 != 3);         //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6);     //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4);     //Определяется как ложь, поскольку 3 меньше 4.

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью ==.

Действительные операторы

Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:

  • a && b - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
&& 0 1
0 0 0
1 0 1
  • a || b - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
|| 0 1
0 0 1
1 1 1
  • !a - Истина, если a ложь. Ложь, если a истина.
! 0 1
1 0

Например:

(1 || 0);         //Определяется как истина, так как выражение 1 истинное
(1 && 0);         //Определяется как ложь, так как выражение 0 ложное
(!1 || 0);        //Определяется как ложь, так как выражение !1 ложное.

Левое/правое значения

Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:

new a = 5;

В этом примере a является левосторонним значением и 5 является правосторонним значением.

Правила:

  • Выражения никогда не будут левосторонними значениями.
  • Переменные являются двумя, левосторонними и правосторонними значениями.

Условия

Условия позволяют Вам запускать код, определенное условие выполнено.

Если соответствует

Если соответствует одно или более условий. Например:

if (a == 5)
{
   /* Код будет запущен, если условие будет истинным */
}

Они могут быть расширены для более сложных случаев:

if (a == 5)
{
   /* Код */
}
else if (a == 6)
{
   /* Код */
}
else if (a == 7)
{
   /* Код */
}

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:

if (a == 5)
{
   /* Код */
}
else
{
   /* Код, который будет запущен если нет истинного выражения */
}

Оператор выбора

Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

switch (a)
{
   case 5:
   {
      /* Код */
   }
   case 6:
   {
      /* Код */
   }
   case 7:
   {
      /* Код */
   }
   case 8, 9, 10:
   {
      /* Код */
   }
   default:
   {
      /* будет запущен, если не одно условие не соответствует */
   }
}

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

Циклы

Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

For циклы

For циклы, это циклы, которые состоят из четырех частей:

  • Оператор инициализации - запускается один раз перед первым циклом.
  • Оператор условия - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
  • Оператор итерации - запускается после каждого цикла.
  • тело цикла - запускается каждый раз, пока оператор условия вычисляется как истинный.
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
   /* тело */
}

Простым примером является функция сложения массива:

new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);
 
SumArray(const array[], count)
{
   new total;
 
   for (new i = 0; i < count; i++)
   {
      total += array[i];
   }
 
   return total;
}

По отдельности:

  • new i = 0 - Создает новую переменную для цикла, и устанавливает её в 0.
  • i < count - Только запускает цикл, если i меньше, чем count. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
  • i++ - Увеличивает i на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов i станет слишком большим, и цикл завершится.

Таким образом, функция SumArray будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

While циклы

While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:

  • Оператор условия - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
  • тело цикла - запускается каждый раз пока цикл выполняется.
while ( /* условие */ )
{
   /* тело */
}

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

/* инициализация */
while ( /* условие */ )
{
   /* тело */
   /* итерация */
}

Вот предыдущий for цикл переписан как while цикл:

SumArray(const array[], count)
{
   new total, i;
 
   while (i < count)
   {
      total += array[i];
      i++;
   }
 
   return total;
}

Существуют также do...while циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

do
{
   /* тело */
}
while ( /* условие */ );

Управление циклами

Существуют два случая, в которых Мы хотели бы контролировать цикл:

  • пропустить одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
  • разорвать цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:

/**
 * Возвращает массив, если индекс значения, или -1, не найдены.
 */
SearchInArray(const array[], count, value)
{
   new index = -1;
 
   for (new i = 0; i < count; i++)
   {
      if (array[i] == value)
      {
         index = i;
         break;
      }
   }
 
   return index;
}

Конечно, эту функцию можно вернуть и способом return i, но пример показывает, как break может остановить цикл.

Кроме того, ключевое слово continue пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

SumEvenNumbers(const array[], count)
{
   new sum;
 
   for (new i = 0; i < count; i++)
   {
      /* If divisibility by 2 is 1, we know it's odd */
      if (array[i] % 2 == 1)
      {
         /* Пропускаем оставшуюся часть итерации цикла */
         continue;
      }
      sum += array[i];
   }
 
   return sum;
}

Область действия

Область действия относится к удобочитаемости кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

new A, B, C;
 
Function1()
{
   new B;
 
   Function2();
}
 
Function2()
{
   new C;
}

В этом примере, A, B, и C имеют глобальную область действия. Их можно увидеть в любой функции. Вместе с тем, B в функции Function1 не является той же переменной, как B на глобальном уровне. Вместо этого она находится в локальной области действия, и поэтому является локально изменяемой.

Кроме того, функции Function1 и Function2 ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции Function1, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:

Function1()
{
   new B;
 
   Function1();
}

В приведенном выше примере, функция Function1 вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия B. Когда функция завершается, B уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

Function1()
{
   new A;
 
   if (A)
   {
      A = 5;
   }
}

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:

Function1()
{
   new A;
 
   if (A)
   {
      new B = 5;
   }
 
   B = 5;
}

Отметим, что B объявляется в новом блоке кода. Это означает, что B доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, B становится не действительной.

Динамические массивы

Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

Function1(size)
{
   new array[size];
 
   /* Код */
}

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

Динамические массивы, действительны только в локальной области действия, так как код не может существовать на глобальном уровне.

Расширенное объявление переменных

Переменные могут быть объявлены более длинным путем чем просто new.

decl

Назначение

По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения = определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово decl (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: decl не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

Объяснение

Например:

new c = 5;
new d;
new String:blah[512];
 
Format(blah, sizeof(blah), "%d %d", c, d);

В этом коде, c равна 5 и d равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, blah является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что blah не должен быть нулевой. В период времени с объявления new и и перемещения в Format(), массив blah никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

new c = 5;
new d;
decl String:blah[512];
 
Format(blah, sizeof(blah), "%d %d", c, d);

Предостережения

Обратная сторона decl состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

new c = 5;
new d;
decl String:blah[512];
 
PrintToServer("%s", blah);
 
Format(blah, sizeof(blah), "%d %d", c, d);

Этот код может привести к падению сервера, так как массив blah может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

new c = 5;
decl d;
decl String:blah[512];
 
Format(blah, sizeof(blah), "%d %d", c, d);

Значение d в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:

decl String:blah[512];
 
blah[0] = '\0';

Золотые правила

  • Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.
  • Не оптимизируйте преждевременно. Кроме того, нет необходимости использовать decl на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

Примечания

Обратите внимание, что decl переменную инициализировать явно, но ТОЛЬКО как строку:

decl String:blah[512] = "a";

However, any other tag will fail to compile, because the purpose of decl is to avoid any initialization:

decl Float:blah[512] = {1.0};

Даже несмотря на то, что строка имеет только один символ, оператор new гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации decl:

decl String:blah[512] = "a";

Приведенный выше код не будет компилироваться, потому что цель decl состоит в том, чтобы избежать каких-либо инициализаций.

static

Ключевое слово static входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

Глобальный static

Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

//file1.inc
static Float:g_value1 = 0.15f;
 
//file2.inc
static Float:g_value2 = 0.15f;

Если плагин включает в себя оба этих файла, он не сможет использовать g_value1 или g_value2. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например private в таких языках, как C++, Java, или C#.

Локальный static

Локальная static переменная является глобальной переменной, которая является видимой лишь из её местной области действия. Например:

MyFunction(inc)
{
   static counter = -1;
 
   counter += inc;
 
   return counter;
}

В этом примере, counter технически глобальная переменная -- она инициализируется один раз как -1 и никогда не инициализируется заново. Оно не существует в наборе. Это означает, что при каждом запуске функции MyFunction, переменная counter и ее хранение в памяти одно и тоже.

Возьмем следающий пример:

MyFunction(5);
MyFunction(6);
MyFunction(10);

В этом примере, counter может быть -1 +5 +6 +10, или 20, поскольку она сохраняется за рамками этой функции. Это может создавать проблемы для рекурсивной функции: если ваша функция может быть рекурсивной, то static, как правило, не является хорошей идеей, если только Ваш код не реентерабельный.

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

Заметим, что statics может существовать в любой локальной области действия:

MyFunction(inc)
{
   if (inc > 0)
   {
      static counter;
      return (counter += inc);
   }
   return -1;
}