View source for The script execution model/Scope and lifetime of variables

There are essentially two scope types in the AviSynth script language:

=== Global scope ===

Every [[Script_variables|variable]] placed in this scope can be freely accessed from any nested block of script code at any level of nesting. That is, you can access a global from the top-level script block, from inside a user [[Script_functions|function]] at any level of recursion, as well as from inside [[Runtime_environment|runtime scripts]].

'''Note:'''
One important precondition for the above rule to apply is that ''you must not have a local variable with the same name as a global one''. If you define a local variable with the same name as a global one, then you can no longer get (read) the value of the global variable in that specific local scope.
This is because AviSynth when given a variable's name it first searches in the current local scope; only if the search fails the global scope is searched. You can however set (write) the global's value, since in that case the use of the keyword <tt>global</tt> distinguishes between a global and a local variable.

=== Local scope ===

Variables placed in this scope can be accessed (read or written) ''only'' from script code within that scope. This allows the isolation of nested local scopes and makes the creation and usage of script functions possible.

The most important local scope is the top-level script scope (the one that is created just before the executing script is parsed and evaluated). All non-global variables defined inside the script-level source code reside there. All the other local scopes are created due to function calls and are nested inside this one.

Nested local scopes result from function or filter calls (plugin writers can create nested scopes through <tt>env->PushContext()</tt> and <tt>env->PopContext()</tt>) and can be created at an arbitrary depth. For example, a recursive user function such as the one below:

 function strfill(string s, int count) {
     return count > 0 ? s + strfill(s, count - 1) : ""
 }

will result during its evaluation in the creation and subsequent destruction of eleven nested local scopes if called with a value ten for its <tt>count</tt> argument.

=== Lifetime of variables ===

The lifetime of variables defined at the global and top-level script (local) scope spans from the time of the definition (that is the first statement that assigns a value to them) to the end of frame serving and the unload of <tt>avisynth.dll</tt>.

The lifetime of variables defined at nested local scopes spans from the time of the definition in the nested local scope to the end of the nested local scope's lifetime. Since nested local scopes result from function / filter calls, the nested scope's lifetime is the lifetime of the function / filter call.

=== A variables scope and lifetime example ===

To clarify the statements of the previous section, the following example demonstrates the scope and lifetime of variables in a moderately complex AviSynth script that also includes runtime scripts.

What the script does is to divide a clip (after some processing tweaks) in 4 equal-sized regions and evaluate the average luma of each region per frame. If this is outside a range defined by two thresholds, the corresponding region is turned to all black (if below) or white (if above) for that frame.

 function Quartile(clip c, int quartile) {
     [[Internal_functions/Control_functions|Assert]](quartile >= 0 && quartile <= 3, "Invalid Quartile!")
     hw = [[Internal_functions/Numeric_functions|Int]](c.[[Clip_properties|Width]]() / 2)
     hh = Int(c.[[Clip_properties|Height]]() / 2)
     return [[Internal_functions/Control_functions|Select]](quartile, \
         [[Crop]](c, 0, 0, hw, hh), Crop(c, hw, 0, hw, hh), \
         Crop(c, 0, hh, hw, hh), Crop(c, hw, hh, hw, hh))
 }
 
 function bracket_luma(clip c, float th1, float th2) {
     Assert(0 <= th1 && th1 < th2 && th2 <= 255, "Invalid thresholds!")
     script =  "th1 = " + [[Internal_functions/Conversion_functions|String]](th1) + Chr(13) + Chr(10) + \
         "th2 = " + String(th2) + """
         avl = [[Internal_functions/Runtime_functions|AverageLuma()]]
         return avl <= th1 ? last.[[BlankClip]]() : (avl >= th2 ? \
             last.BlankClip(color=color_white) : last)
         """
     return [[ScriptClip]](c, script)
 }
 
 clp = [[AviSource]]("myclip.avi")
 clp = [[Tweak]](clp, hue=20, sat=1.1)
 threshold1 = 12.0
 threshold2 = 78.0
 q0 = Quartile(clp, 0).bracket_luma(threshold1, threshold2)
 q1 = Quartile(clp, 1).bracket_luma(threshold1, threshold2)
 q2 = Quartile(clp, 2).bracket_luma(threshold1, threshold2)
 q3 = Quartile(clp, 3).bracket_luma(threshold1, threshold2)
 [[StackVertical]](StackHorizontal(q0, q1), [[StackHorizontal]](q2, q3))
 
The scope and lifetime of all variables in the example script is presented in the following timeline (the <tt>color_white</tt> global is from the autoloaded .avsi that ships with AviSynth):

 +-- scope --+------- parsing phase ---------------------->+----- frame serving phase ------->+
 |           |                                                                                |
 | global    |color_white - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ->|
 +-----------+---------------------------------------------+----------------------------------|
 | local,    |clp - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ->|
 | top-level | threshold1,threshold2- - - - - - - - - - - - - - - - - - - - - - - - - - - - ->|
 |           |                            q0- -q1- -q2- -q3 - - - - - - - - - - - - - - - - ->|
 |           |                                             |th1,th2,avl - - - - - - - - - - ->|
 +-----------+---------------------------------------------+----------------------------------|
 | local,    |   c,  - - - ->|           |                |
 | Quartile  |   quartile, ->|           | repeated       |
 | function  |    hw,hh- - ->|           | three times,   |
 +-----------+-------------------------->| in immediate ->|
 | local,    |               |c, - - - ->| succession     |
 | bracket_l.|               |th1,th2, ->|                |
 | function  |               | script- ->|                |
 +-----------+---------------------------------------------+----------------------------------|

=== Code-injecting language facilities and scopes ===

There are certain language constructs (functions, filters and control structures) that allow the injection of code in the script, ie the execution of arbitrary sequences of AviSynth script language [[AviSynth_Syntax|statements]]. 

This is a ''very'' useful functionality that allows among other things dynamic code evaluation, the creation of [[Block_statements|block statements]] and [[Arrays|arrays]], the organisation of AviSynth code in libraries, etc. However, there are some subtle issues regarding variables' scope and visibility that can lead to surprises if not fully understood. 

==== Import and Eval ====

[[Import]]() and [[Internal_functions/Control_functions|Eval]]() evaluate the passed-in script source code in the context of the current local scope. 

This means that variables contained in the top-level scope of the imported script or in the code string passed to Eval() are created inside the current local scope and become available for read/write to the following script source code. For example:

'''1. File "a.avs"'''
 x = 12
 y = 24
 c = [[BlankClip]](pixel_type="[[YV12]]", color=color_orange, width=240, height=180)

'''2. File "b.avs"'''
 [[Import]]("a.avs")
 [[AviSource]]("myvideo.avi")
 [[Levels]]('''x''', 1.0, 255, '''y''', 242)
 [[Overlay]]('''c''', x=last.Width-320, y=last.Height-240, mode="chroma")

In addition, the imported script or the code string passed to Eval() can use previously defined in that scope local variables (as well as globals, of course). For example (the use of multiline triply quoted strings makes easier the writing of [[Block_statements|block statements]]):

 x = 5
 AviSource("aclip.avi")
 f = [[Clip_properties|Framecount]]()
 f < 100 ? [[Internal_functions/Control_functions|Eval]]("""
     [[Trim]](x, f-2)
     x = 0
 """) : Eval("""
     Trim(x, 15*x + 30)
     x = 1
 """)
 x == 0 ? [[Invert]]() : [[Subtitle]](String(last.Framecount))

Especially the later is something that you must always keep in mind -mostly for [[Import]]() since the code is not immediately visible; only the filename shows up in the script- because it has the potential to introduce bugs by unexpected overriding of a variable's value.

Consider, the following example:

'''1. File "mylib.avsi"'''
 function preset(int num) { # 0 to 3
     return [[Internal_functions/Control_functions|Select]](num, AviSource("..."), AviSource("..."), AviSource("..."), AviSource("..."))
 }
 global def_preset = preset(0)
 
'''2. File "myscript.avs"'''
 global def_preset = [[AviSource]]("myfav.avi")
 Import("mylib.avsi")
 [[Tweak]](def_preset, hue=20) # oops, using clip from mylib.avsi instead of myscript.avs!
 ...

The imported script changed a previously defined variable and the results will now be surprising (until of course the bug is discovered).

However, this same feature has a number of interesting possibilities, for example:

* You can define sub-scripts that communicate with the parent script through a defined set of variables.
* You can create libraries (AviSynth include files) that perform initialisation code based on "environment" variables (the ones you set in the parent script before importing) and / or return status information (through a variable that they set at the global or top-script level code)
* You can implement [[Block_statements|block statements]].

'''Note:''' To test for the existence of input/output variables in the above scenarios try to read their value in a <tt>try..catch</tt> block; else your script will die hard if for any reason they do not exist.

==== Runtime scripts ====

Local variables inside runtime filters' scripts are '''always''' bound to the top-level script local scope; even if the filter calls were made inside a user function. This is because the parsing of runtime scripts is done ''after'' the parsing of the script, at the frame serving phase. At that point  in script execution, nested local scopes have already vanished and only the global and the top-level script local scopes survive.

The same is true for the [[Runtime_environment|special variables]] set by the runtime filters (such as for example <tt>current_frame</tt>); they are defined at the top-level script local scope.

Some consequences of the above setup are the following:

* You can use top-level script local variables inside the runtime scripts to pass information, just as is customary to do with global ones.
* You must be careful if you define local variables in your runtime scripts not to clash with local variables in other runtime scripts in the filter chain. This is also true for globals, but globals are typically used for inter-filter communication; use of locals is not so common and thus may be overlooked by script writers.
* Overriding a variable (either local or global) does not have an effect on the main script, because the evaluation of the main script is done at the parsing phase, before the execution of any runtime script.
* When examining the way that a variable will be modified by a chain of runtime scripts, you must remember that the evaluation of scripts is done from bottom to top, just like the fetching of frames.

Consider the following example:

 [[AviSource]]("myclip.avi")
 x = 5
 fc = Framecount()
 fc > 2x ? [[Trim]](x, fc - x) : Trim(0, fc - x)
 fc = Framecount()
 [[ScriptClip]]("""[[Subtitle]]("and the value of x is : " + String(x))""")
 FrameEvaluate("x = (x % 3 == (fc - x - 1) % 3) ? x + 2 : x - 1")
 [[FrameEvaluate]]("x = current_frame")

The assignment <tt>x = 5</tt> at the main script is used to control trimming of the source clip. <tt>x</tt> is passed as argument in the [[Trim]] filter during the script's parsing phase. Thus the modifications by the runtime scripts that start at the frame serving phase have no effect on the values passed to Trim. 

By the time the first frame is fetched, <tt>x</tt> will have been overwritten by the <tt>x = current_frame</tt> assignment in the last [[FrameEvaluate]] filter's runtime script. Thus its value in the script has no effect (in this particular case) on the results of the runtime filter's processing.

Here, using <tt>x</tt> in all runtime filter scripts does not pose a naming clash problem. <tt>x</tt> is the variable used to communicate state information along the runtime filter chain. However, if we had needed a conditional assignment by frame number and we had accidentally used the following runtime script in place of the last FrameEvaluate line,

 FrameEvaluate("""
     fc = 12
     x = current_frame < fc ? current_frame : fc
     """)

then there would be a clash with the use of <tt>fc</tt> in the previous line (the clips framecount would have been overwritten with an unrelated value) and the logic of our processing would be in error.

Similarly, a ''later'' assignment to <tt>fc</tt> in the ''main'' script would alter the value seen by the runtime script. The point to note is that the value in the run-time script is evaluated at a later point in time, which is after all statements in the main script have been evaluated.

==== The try...catch block ====

This may seem surprising at first, but the <tt>try...catch</tt> block does inject code in the script (at the scope that contains it). If this code defines new variables, then those variables are available to the code in the section that follows the <tt>try...catch</tt> block. More specifically, there are two possibilities:

* ''No error'' occurs inside the <tt>try{...}</tt> section.
:# All statements of the code contained in the <tt>try{...}</tt> section are evaluated and affect the script code that follows.
* An error ''does'' occur inside the <tt>try{...}</tt> section.
:# Statements of the code contained in the <tt>try{...}</tt> section up to the point of error are evaluated and affect the script code that follows. 
:# All statements of the code contained in the <tt>catch{...}</tt> section are evaluated and affect the script code that follows. 
:# The variable that is used the <tt>catch{...}</tt> section to store the error message becomes available to the script code that follows.

The following example code excerpt clarifies the above:

 a = ... # it is assumed that the (missing) code may result in a being either 1 or 0
 try {
     y = 3
     x = 6 / a  # if a == 0 this will lead to an error
     z = 12
 }
 catch (msg) {
     NOP 
 }
 ...code that follows...

Now, if <tt>a</tt> is ''not'' zero at the point the <tt>try...catch</tt> block is evaluated, then three new local variables in the current scope will be created (<tt>x</tt>, <tt>y</tt> and <tt>z</tt>) and be available for use by the code that follows.

If however, <tt>a</tt> ''is'' zero, then from the three variables in the try section only <tt>y</tt> will be created; in addition, since the catch section will be evaluated, <tt>msg</tt> will be created. Thus the variables available for use by the code that follows will be <tt>y</tt> and <tt>msg</tt>.

----
Back to the [[The_script_execution_model|script execution model]]. 
[[Category:AviSynth_Syntax]]
[[Category:Scripting_Reference]]