Re-usable Procedures: Difference between revisions
No edit summary |
No edit summary |
||
| Line 8: | Line 8: | ||
The topics below summarize each of these considerations. | The topics below summarize each of these considerations. | ||
=== | ===Inherit Caller's Context=== | ||
When invoked, procedures inherit the initial script context of their caller. For example, if a Description script calls a procedure, the pick or thing that is the initial context of the script is also the initial context within the procedure. There is one exception to this, which is discussed in the topic on Generic Procedures (below). | |||
=== | ===No Parameters=== | ||
Unlike most programming languages, procedures have no parameters. You cannot pass parameters to procedures in the way that traditional programming languages do. However, you '''can''' pass information between caller and procedure via the use of variables (see below). | |||
===Inherit Caller's Local Variables=== | ===Inherit Caller's Local Variables=== | ||
Procedures inherit all local variables of the calling script. However, you must still declare each local variable within the procedure so that the compiler knows that you intend to use them. When that is done, the value of each variable will be inherited when the procedure is called and can be accessed normally via the variable within the procedure. Using local variables, you can pass information between the calling script and the procedure. Changes made to variables within the procedure will remain in effect upon return to the calling script, so you can use this technique to pass information both from the script into the procedure and back out from the procedure to the calling script upon return. | |||
===Script Type Vs. Context=== | ===Script Type Vs. Context=== | ||
All procedures must be assigned either a specific script type or a more general script context. This assignment dictates important behaviors for the procedure that impact which scripts can legally call the procedure. Scripts can only call procedures that are assigned a compatible classification. Either the script type must match exactly or the script context must match generally. For example, you cannot call a procedure with "container" context from within an Eval Script, since that script has a "pick" context. | |||
There is a distinct advantage to designating a specific script type for a procedure. If a script calls a procedure with the same script type, then the procedure has full access to all of the special symbols defined for the script. The special symbols behave just like inherited variables and are shared back and forth. If a procedure does not share the identical script type, special symbols are not accessible. | |||
There is a different advantage to using a more general script context for a procedure. By using a general script context, a procedure becomes much more versatile. The procedure can be used from multiple different scripts of different types. For many scripts, using a matching context is preferable, since the procedure can then be re-used by more scripts. | |||
The complete list of script types and contexts available for procedures is specified within the [[Kit Reference]] documentation. | |||
===Using Pick and Container Context=== | ===Using Pick and Container Context=== | ||
| Line 34: | Line 38: | ||
generic allows use with any script | generic allows use with any script | ||
6. Procedures can also be declared as generic, in which case no access to special symbols is possible from within the procedure. The advantage of a generic procedure is that it can be called from scripts of different types, but it comes with this critical limitation. If you need to access a special symbol from within a generic procedures, the calling script must declare a local variable and copy the special symbol value into it prior to calling the procedure. | 6. Procedures can also be declared as generic, in which case no access to special symbols is possible from within the procedure. The advantage of a generic procedure is that it can be called from scripts of different types, but it comes with this critical limitation. If you need to access a special symbol from within a generic procedures, the calling script must declare a local variable and copy the special symbol value into it prior to calling the procedure. | ||
another type of generic procedure has no context and can be freely called from anywhere | |||
no initial context means all accesses must start with a global context, such as the "hero" | |||
===Calling Other Procedures=== | ===Calling Other Procedures=== | ||
4. Procedures are allowed to call other procedures at this time. | 4. Procedures are allowed to call other procedures at this time. | ||
Revision as of 13:41, 18 November 2008
[Context: HL Kit … Basic Concepts and Terminology … Scripting Language]
Procedures provide the means to define script logic in a single location and re-use that logic within multiple scripts by calling the procedure from each of those scripts. Procedures are an extremely convenient tool and are used regularly for a variety of purposes.
There are a number of important considerations that come in to play when using procedures. Some are fundamental to the nature of procedures, while others are selectable, allowing you to choose between various capabilities to better tailor the procedure to your needs.
The topics below summarize each of these considerations.
Inherit Caller's Context
When invoked, procedures inherit the initial script context of their caller. For example, if a Description script calls a procedure, the pick or thing that is the initial context of the script is also the initial context within the procedure. There is one exception to this, which is discussed in the topic on Generic Procedures (below).
No Parameters
Unlike most programming languages, procedures have no parameters. You cannot pass parameters to procedures in the way that traditional programming languages do. However, you can pass information between caller and procedure via the use of variables (see below).
Inherit Caller's Local Variables
Procedures inherit all local variables of the calling script. However, you must still declare each local variable within the procedure so that the compiler knows that you intend to use them. When that is done, the value of each variable will be inherited when the procedure is called and can be accessed normally via the variable within the procedure. Using local variables, you can pass information between the calling script and the procedure. Changes made to variables within the procedure will remain in effect upon return to the calling script, so you can use this technique to pass information both from the script into the procedure and back out from the procedure to the calling script upon return.
Script Type Vs. Context
All procedures must be assigned either a specific script type or a more general script context. This assignment dictates important behaviors for the procedure that impact which scripts can legally call the procedure. Scripts can only call procedures that are assigned a compatible classification. Either the script type must match exactly or the script context must match generally. For example, you cannot call a procedure with "container" context from within an Eval Script, since that script has a "pick" context.
There is a distinct advantage to designating a specific script type for a procedure. If a script calls a procedure with the same script type, then the procedure has full access to all of the special symbols defined for the script. The special symbols behave just like inherited variables and are shared back and forth. If a procedure does not share the identical script type, special symbols are not accessible.
There is a different advantage to using a more general script context for a procedure. By using a general script context, a procedure becomes much more versatile. The procedure can be used from multiple different scripts of different types. For many scripts, using a matching context is preferable, since the procedure can then be re-used by more scripts.
The complete list of script types and contexts available for procedures is specified within the Kit Reference documentation.
Using Pick and Container Context
pick and container procedures for re-use with preserved context
Generic Procedures
generic allows use with any script
6. Procedures can also be declared as generic, in which case no access to special symbols is possible from within the procedure. The advantage of a generic procedure is that it can be called from scripts of different types, but it comes with this critical limitation. If you need to access a special symbol from within a generic procedures, the calling script must declare a local variable and copy the special symbol value into it prior to calling the procedure.
another type of generic procedure has no context and can be freely called from anywhere no initial context means all accesses must start with a global context, such as the "hero"
Calling Other Procedures
4. Procedures are allowed to call other procedures at this time.
