Difference between revisions of "Re-usable Procedures"

From HLKitWiki
Jump to: navigation, search
Line 10: Line 10:
 
===Inherit Caller's Context===
 
===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).
+
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===
 
===No Parameters===
Line 30: Line 30:
 
The complete list of script types and contexts available for procedures is specified within the [[Kit Reference]] documentation.
 
The complete list of script types and contexts available for procedures is specified within the [[Kit Reference]] documentation.
  
===Using Pick and Container Context===
+
==="Any" Procedures===
  
pick and container procedures for re-use with preserved context
+
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.
  
===Generic Procedures===
+
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.
 
+
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===
 
===Calling Other Procedures===
  
  4. Procedures are allowed to call other procedures at this time.
+
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.

Revision as of 06:01, 18 November 2008

[Context: HL KitBasic Concepts and TerminologyScripting 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 "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.