Просмотр исходного текста страницы Справка по функциям

[[Файл:Symbol_error.png]] '''Статья не закончена!'''
[[Category:Незаконченная статья]]

Функции(''англ.'' Functions) это единицы работы всех систем, они представляют из себя нечто большее, чем простое выражение, и могут принимать различные параметры и возвращать значение тому, кто их вызвал.

== Объявление функции ==
 <функция> ::= <заголовок функции>
                [<блок функции>
                'endFunction']

За заголовком функции всегда должен следовать блок функции и [[Справка по ключевым словам|ключевое слово]] "EndFunction", за исключением тех случаев, когда функция имеет флажок native (это те функции, которые доступны в игре, одним словом, определены в движке игры).

=== Заголовок функции ===
 <заголовок функции> ::= [<тип>] 'Function' <идентификатор> '(' [<параметры>] ')' ('global' | 'native')* <флажки>*

Заголовок функции начинается (не обязательно) с типа данных, возвращаемых функцией, и затем следует имя функции, её параметры (если есть), и какие-либо модификаторы и флажки.

[[Справка по идентификаторам|Идентификатор]], используемый для задания имени функции не может конфликтовать с какой-либо другой функцией в данном скрипте. Если идентификатор совпадает с функцией в скрипте-родителе, то возвращаемый тип данных и параметры должны совпадать с теми, что находятся в версии функции в скрипте-родителе - и ещё, эта функция переопределит родительскую.

Флажок "Global" указывает на функцию, которая не будет запущена на внутриигровом объекте, и которая не имеет переменной "Self". 
 
Флажок "Native" указывает на функцию, которая не имеет тела функции, потому что она реализуется самой игрой. Если вы добавите флажок native к функции, не представленной игрой, то компилятор не сообщит об этом, но игра выдаст ошибку. Так же этот флажок не может быть указан более одного раза.
<br/><br/>
::{|style="border-collapse: separate; border-spacing: 0; border-width: 1px; border-style: solid; border-color: #000; padding: 0"
|-
|style="border-style: solid; border-width: 0"|[[Image:InDepth.jpg|48px]]
|style="border-style: solid; border-width: 0"|<!--Если вам стало интересно что за такая переменная "Self", то можно сказать что она унаследована из объектно-ориентированного программирования, и наследуется, как и все остальные понятия класса и экземпляры класса, которые так же называются объектами. Типичным примером для объяснения связи класса(class)/экземпляра(instance) можно назвать различие между чертежом автомобиля и реальным автомобилем, который был сделан по этому чертежу. У вас может быть куча машин на базе одного чертежа. For anything useful, you can't know all the cars that are going to be created from your blueprint, поэтому вам нужен метод определения относительно того, какой автомобиль имеет некоторые функция, которые были вызваны/используются. To be direct, you can't turn on the radio of a blueprint, it's a piece of paper. But you can do it in a real car, made from the blueprint. One might tune in to a hard rock station. And another car could tune to a station that plays Rebecca Black's song "Friday" all day. Now, Replace the word "blueprint" with "class" and "car" with "instance/object" in your head. That difference is crucial, capture it. The way you find out which object is being possibly modified by a function is by silently pushing in an additional hidden parameter to a function which contains the memory address of the "victim" object, of the logical name "Self". In some languages, '''self''' is called '''this'''.

On a serious note, one could ask: "'''Why should I ever want to use this "Self" variable when I can simply change any variable I want directly? I know they exist in the blueprint, therefore they are also in the instance. That's the whole point, is it not?'''" Sort of, young samurai. But not really, everything you do actually is resolved by the compiler to use the '''this/self''' pointer. If you change an integer member variable '''something''' to 5, what you do is: "'''something = 5;'''". What actually happens internally is "'''self->something = 5;'''". '''Self''' is your silent guardian, a watchful protector... A dark knight.

Here's just a simple taste from general programming which includes '''Self''''s explicit usage, imagine that you've got a function invoked on an object (sometimes called a '''non-static member function/method''' or perhaps an '''instance-level member function/method''') that takes a parameter that points to an object of the same class. And you want to make sure you're not being fed the very object the function has been invoked upon. That mouthful is referred to as "self-reference". With "Self", you can check whether pObject is equal to Self and prevent damaging or unnecessary code from executing. If you can't think of a useful application of this example, it comes in handy with dynamic memory management and functions called setters.

Here, let's pretend that you are trying to change an object crucial to your application and you want to release the old one because you're a good memory citizen who cares about his users and their limited memory resources. So, you want to first release the old object and then set the pointer to the new one, right? But what if a nasty scenario occurs where you replace the object with itself? You release the old object, set the pointer to the memory address of the "new" object (which is, actually, the old object), try to dereference it (a fancy word for "use it") and boom - a wild unicorn appears and destroys your application '''if you're lucky'''. Usually, the memory is just cleared to be overwritten, the system might not use it immediately, therefore, in some cases - your application could work and make your life miserable by reports of crashing. You made a dangling pointer which references an object that was released (by you, a moment ago). Do you, perhaps, see how you could solve this? Yes, exactly. If newObject is NOT equal to Self (newObject != Self), then release the object referenced by Self and change the Self pointer/variable to point to newObject (Self = newObject). And you've solved all of your life's troubles. Kittens are purring. Birds are singing. And gamers are cursing at the dragon that killed them because your game or mod is awesome.
-->
Переменная "self" является естественным следствием объектно-ориентированного программирования. Объектно-ориентированное программирование опирается на понятие абстрактного класса и экземпляра этого класса (экземпляр можно также назвать объектом.)

Связь между классом и экземпляром похожа на разницу между чертежом автомобиля и реальным автомобилем, который сделан по этому чертежу. Всего лишь один чертеж может являться базой для множества автомобилей. Чертеж - это и есть абстракция. Вы не можете взаимодействовать с ним. Например, вы не можете включить радио автомобиля на чертеже. Это кусок бумаги, не более. Для того, чтобы включить радио, вам нужно взаимодействовать с реальным автомобилем. Чертеж - это класс, а автомобиль - это объект. The way you find out which object is being acted upon by a function is to refer to the self. Например, ''self.TurnOn(theRadio)'' включит радио у автомобиля, который вызвал функцию, и при этом, только у одного этого автомобиля.

All functions are actually resolved by the compiler to use the '''this/self''' pointer. If a script changes an integer variable '''someInt''' to 5, what it looks like to us is: '''someInt = 5'''. Internally, that variable is labeled with, and considered a component of, the object that calls it, which could be written as '''self.someInt = 5'''

Простой пример: представим себе функцию, вызываемую на объекте, который принимает параметр, указывающий на другой объект того же класса: '''car1.Ram(car2)''' (которая должна протаранить вашим автомобилем другой). Очевидно, что автомобиль не может сам себя протаранить. Используя переменную "Self", мы может быть уверены, что car2 не будет эквивалентна Self и предотвратим повреждения или выполнение ненужного кода:
<br>
<source lang="papyrus">
;Функция вызывается на одном автомобиле типа такого.
Car1.Ram(car2)

;Когда мы пишем функцию:
function Ram(object someVehicle)

;Если someVehicle это тот же автомобиль, на котором изначально вызывалась функция,
;убиваем функцию, не позволяя автомобилю нанести себе самому повреждения.
 if(someVehicle == self)
    return
 else
    self.Moveto(someVehicle)
 endIf
endFunction
</source>
<br/>
Another example is a script that is trying to release an object it no longer needs so that the reference no longer consumes memory. However due to the its complexities, the script may accidentally end up referencing the same object. A reference to an object that was expected to be released is called a dangling pointer, and it can cause crashes or other problems as the application progresses. By comparing newObject to Self (''if(newObject != Self)''), we can be sure that when the old object is released it will be properly replaced by newObject.


|}

=== Параметры ===
 <параметры> ::= <параметр> (',' <параметр>)*
 <параметр>  ::= <тип> <идентификатор> ['=' <константа>]

Список параметров - это разделенный запятыми список типов и идентификаторов, которые указывают на различные параметры, принимаемые функцией. После каждого параметра может быть опционально знак равно и константа, которые указывает, что параметр имеет значение по-умолчанию. Если у параметра есть значение по-умолчанию(''англ.'' default), то каждый параметр после этого должен иметь значение по-умолчанию.

Параметры, это по сути [[Справка по переменным|переменные]], к которым функция имеет доступ для получения начальных значений, установленных пользователем.

=== Блок функции ===
 <блок функции> ::= <statement>*

Блок функции содержит 0 или более [[Справка по инструкциям|инструкций]]. Здесь выполняется основная работа функции.

=== Примеры ===
<source lang="papyrus">
; Простая функция, которая складывает два значения вместе и возвращает резуальтат
; Глобальная(global), потому что не нуждается в переменной self
int Function AddTwo(int a, int b) global
  return a + b
endFunction
</source>
<br/>
<source lang="papyrus">
; Функция, которая увеличивает значение в этом скрипте на указанную величину.
; Величина имеет значение по-умолчанию и равно 1 (так что вызывающий не должен передавать её)
Function IncrementValue(int howMuch = 1)
  myValue += howMuch
endFunction
</source>

== Специальные переменные ==
There are two special variables in a function, but only in a non-global one. "Self" refers to the instance of the script that the function is running on, and is useful if you want to pass yourself as a parameter to another function somewhere else.

"Parent" is only used to call a parent script's version of a function, in the case where you extend the parent.

=== Примеры ===
<source lang="papyrus">
; Pass our self off to another function
SomeObject.OtherFunction(self)
</source>
<br/>
<source lang="papyrus">
; Call the parent's version of DoStuff, ignoring our local definition
Parent.DoStuff()
</source>

== Вызов функций ==
Global function:
 [<identifier> '.'] <identifier> '(' [<параметры>] ')'
Non-global function:
 [<выражение> '.'] <identifier> '(' [<параметры>] ')'

Calling a function simply involves using the function's [[Identifier Reference|identifier]], followed by parenthesis, and any parameters that the function takes. The return value of the function is the result of the function call and can be assigned to a variable, or used to call another function or property.

If you are calling a function from outside the current script or script fragment, note that no properties defined in the function's own script will be valid when it is called. Therefore you must pass any properties you wish to use in the function as parameters, defined in the calling script. 

If you are calling a global function and the function's owning script isn't the current script or isn't [[Script File Structure#Imports|imported]], then you must prefix it with the name of the script the function resides in.

If you are calling a non-global function and it isn't on yourself, then you must prefix it with the object you want to call it on.

=== Параметры ===
 <параметры> ::= <параметр> (',' <параметр>)*
 <параметр>  ::= [<идентификатор> '='] <выражение>

The parameter list is a comma-separated list of expressions in the same order as the parameters are listed in the function definition. If a parameter is optional, it does not have to be passed (the default value is inserted by the compiler into the call location). You may specify parameters out of order by prefixing the expression with the identifier of the parameter (matching the name of the parameter in the definition) followed by an equals sign.

=== Примеры ===
<source lang="papyrus">
; Call the function: MyFunction(int a, int b) and get the result and put it in x
x = MyFunction(1, 2)
</source>
<br/>
<source lang="papyrus">
; Call the function DefaultFunction(float a, float b, float c = 0.0, float d = 1.0) on MyObject,
; but only pass in the first three parameters
MyObject.DefaultFunction(4.0, 2.0, 1.0)
</source>
<br/>
<source lang="papyrus">
; Call the function DefaultFunction(float a, float b, float c = 0.0, float d = 1.0), but specify
; argument d out of order because we want c to keep the default it has
DefaultFunction(5.0, 2.4, d = 2.0)
</source>
<br/>
<source lang="papyrus">
; Call the global function MyGlobal() in the Utility script
Utility.MyGlobal()
</source>

== Доступ к функциям из других скриптов ==

There are several methods for accessing one script's functions (or properties, states, etc...) from another script. For the sake of the following examples, let us assume we are working on ScriptA, but we need to access a function that is in ScriptB.

=== Метод первый: Setting up the Target Script as a Filled Property ===

Declare the script that you want to access (ScriptB) ''as a property within'' the script you are trying to access it from (ScriptA).
*This method is best when you only need access to a script that has a single instance (like a script attached to a specific Quest or ReferenceAlias). This is because you will have to choose the ''specific instance'' of the script you want to access when you fill the property in the CK.

<br>'''Example:'''
<source lang="papyrus">
myRefAliasScript property refScript auto      ;fill this property with your quest in the CK editor

;...
refScript.myRefAliasScriptFunction01()
refScript.myRefAliasScriptFunction02()        ;access two functions that are in the reference alias script
</source>


=== Метод второй: Access the Target Script by Creating a Variable On-the-fly ===

Declare a variable that has the type of the target script (ScriptB) that you want to access. Then set that variable to equal the instance of ScriptB that needs to be accessed. This method is best for times when:
*(1) There are more than one instances of ScriptB that need to be differentiated (ScriptB is attached to several different Actors, for example)
*(2) ScriptB does not exist before run-time, so a property cannot be filled with it (ScriptB is attached to an ObjectReference that doesn't exist until ScriptA PlaceAtMe()'s it into existence, for example)

<br>'''Example One:'''<br>
''Access the script functions on a created ObjectReference:''
<source lang="papyrus">
ObjectReference Pony1 = PlayerRef.PlaceAtMe(myCustomPony)   ;create two ponies. Let us assume that myCustomPony is a base Actor that has 'PonyScript.psc' attached to it.
ObjectReference Pony2 = PlayerRef.PlaceAtMe(myCustomPony)
PonyScript Pony1Script = Pony1 as PonyScript                ;declare two variables, each pointing to the INSTANCE of PonyScript attached to one particular pony
PonyScript Pony2Script = Pony2 as PonyScript                
Pony1Script.groomPony()                                     ;groom pony one, using the groomPony() function in (its instance of) PonyScript
Pony2Script.killPony()                                      ;kill pony two, using the killPony() function in (its instance of) PonyScript
</source>

<br>Note: sometimes you will have to cast the object with ScriptB attached to it before declaring the variable will work. Let us say that Pony1 was an Actor instead of an ObjectReference, for instance. Since PonyScript extends ObjectReference, we first need to cast Pony1 ''as an ObjectReference'' before we can cast it ''as a PonyScript'', otherwise the compiler will throw out errors:

<source lang="papyrus">
Actor Pony1 = somePony
PonyScript Pony1Script = (Pony1 as ObjectReference) as PonyScript
</source><br><br>

'''Example Two:'''<br>
''Find an Actor's linked reference, and conditionally access the script functions on that reference:''
<source lang="papyrus">
ObjectReference possibleTable1 = Actor1.GetLinkedRef()
if (possibleTable1 as Furniture) == magicTable                         ;is the actor linked to a magicTable?
  magicTableScript TableScript1 = possibleTable1 as magicTableScript
  TableScript1.explode()                                               ;if so, use the magicTable's script function to make the magicTable explode!
endif
</source>
<br><br>

== Примечания ==
* The nomenclature of Bethesda's functions' arguments is consistent, prefixing argument names such that their nature is easily determined. The naming convention is as follows, each prefix denoting the corresponding qualities:

: a : Argument :: b : Bool :: f : Float :: i : Int :: p : Pointer :: s : String :: k : Form/Alias :: u : Unsigned

: auiCount, for instance, is an unsigned integer argument while asFileName is a string argument. Note that 'p' and 'k', for Papyrus' purposes, are interchangeable and that Papyrus does not actually have pointers.

== Баги ==
* In typed functions, the compiler does not properly check all code paths for returns with values. If the function exits without providing a return value, the result is indeterminate and causes unexplained failures throughout related scripts (possibly due to stack corruption).

= Смотрите так же =
*[[:Category:Events|Events]]
*[[Events Reference]]
*[[Flag_Reference#Function_Flags|Function Flags]]



[[Category:Скриптинг]]
[[Category:Papyrus]]
[[Category:Справка по языку Papyrus]]