Re-usable Procedures: Difference between revisions

From HLKitWiki
Jump to navigationJump to search
New page: Category:Basic Concepts and Terminology [Context: HL KitBasic Concepts and TerminologyScripting Language] Procedures provide the means to define scrip...
 
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Basic Concepts and Terminology]]
{{context|Kit Reference}}
[Context: [[Home|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 various purposes.  
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.


script type vs. context - controls access to special symbols
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.


pick and container procedures for re-use with preserved context
The topics below summarize each of these considerations.


generic allows use with any script
===Inherit Caller's Context===


inherit the context of the caller
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 "Any" 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).


However, procedures also have a variety of special characteristics that must be properly accounted for by an author. Those characteristics are outlined below.
===Inherit Caller's Local Variables===


  1. Procedures have no parameters, so you cannot pass parameters to procedures in the way that traditional programming languages do so.
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.
  2. Procedures inherit all local variables of the calling script. You do still need to declare these local variables within the procedure so that the compiler knows how you intend to use them, but their values will be inherited when the procedure is called. 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 in either direction between the script and procedure.
 
  3. All procedures must be assigned a classification (or context). Scripts can only call procedures that are assigned a compatible classification. For example, you cannot call a procedure with "container" context from within an Eval Script, since that script has a "pick" context.
===Script Type Vs. Context===
  4. Procedures are not allowed to call other procedures at this time.
 
  5. If a procedure is designated as having a specific script type, then you can access the exact same special symbols from within the procedure that can be accessed by that script type. These special symbols inherit they meaning from the calling script, just like variables.
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.
  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.
 
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.
 
==="Any" Procedures===
 
There is a special type of procedure that can be called from absolutely '''any''' script. In order to make this possible, though, the procedure must make an additional concession to ensure compatability. The procedure possesses '''no''' initial script context. This is because the same procedure could be called from different scripts, where each calling script has a different initial context.
 
The implications of having no context are significant. Without an initial context, the procedure cannot perform transitions to anything based on an initial context. This means that the only things that can be done are to either operate upon variables (which are shared with the caller) or specify  a "safe" context and transition from there. For example, the procedure is always free to start with the "hero" context and locate the specific information it needs, since there is always a hero that can be identified and used.
 
===Calling Other Procedures===
 
Procedures '''are''' allowed to call other procedures. All of the rules above apply to procedures that are called from other procedures. The same variable space is shared, all of the special symbols are shared, and all of the rules regarding script type and context apply equally to any procedure, even one that is not called directly from a script.

Latest revision as of 23:11, 4 December 2008

Context: HL Kit … Kit Reference 

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 "Any" 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.

"Any" Procedures

There is a special type of procedure that can be called from absolutely any script. In order to make this possible, though, the procedure must make an additional concession to ensure compatability. The procedure possesses no initial script context. This is because the same procedure could be called from different scripts, where each calling script has a different initial context.

The implications of having no context are significant. Without an initial context, the procedure cannot perform transitions to anything based on an initial context. This means that the only things that can be done are to either operate upon variables (which are shared with the caller) or specify a "safe" context and transition from there. For example, the procedure is always free to start with the "hero" context and locate the specific information it needs, since there is always a hero that can be identified and used.

Calling Other Procedures

Procedures are allowed to call other procedures. All of the rules above apply to procedures that are called from other procedures. The same variable space is shared, all of the special symbols are shared, and all of the rules regarding script type and context apply equally to any procedure, even one that is not called directly from a script.