4
edits
m (→Checking Module Dependancies: spelling) |
m (typos) |
||
Line 37: | Line 37: | ||
already been used. Perhaps this will evolve over time and become | already been used. Perhaps this will evolve over time and become | ||
more formalized and/or automated. After obtaining a unique module | more formalized and/or automated. After obtaining a unique module | ||
name, it can then be used to guarantee | name, it can then be used to guarantee uniqueness of all other names | ||
having global scope as outlined below. | having global scope as outlined below. | ||
Line 50: | Line 50: | ||
; Uppercase Notation : all uppercase characters, underscore | ; Uppercase Notation : all uppercase characters, underscore | ||
characters are used to optionally | characters are used to optionally separate words. | ||
; Lowercase Notation : all lowercase characters, underscore | ; Lowercase Notation : all lowercase characters, underscore | ||
characters are used to optionally | characters are used to optionally separate words. | ||
Line 62: | Line 62: | ||
characters to get optimal use of the Script Editor's auto-complete | characters to get optimal use of the Script Editor's auto-complete | ||
feature. More than 16 characters makes using the module overly | feature. More than 16 characters makes using the module overly | ||
burdensome. | |||
<pre> | <pre> | ||
Line 89: | Line 89: | ||
Enumerated data types are defined in the Module Header and have | Enumerated data types are defined in the Module Header and have | ||
global scope. { At the time of this writing, it is not clear to the | global scope. { At the time of this writing, it is not clear to the | ||
author what scope or other | author what scope or other characteristics enums defined in the Module | ||
Script have } The enumerated types name is formed using Camel | Script have } The enumerated types name is formed using Camel | ||
Notation prefixed by the module name. The enum value names are | Notation prefixed by the module name. The enum value names are | ||
Line 143: | Line 143: | ||
speaking functions can be local or global in scope. However, AGS | speaking functions can be local or global in scope. However, AGS | ||
does not permit forward references, so in practice local functions | does not permit forward references, so in practice local functions | ||
are often categorized as being | are often categorized as being either a utility function or an | ||
application function. The intent of these groupings is to organize | application function. The intent of these groupings is to organize | ||
the Module Script so that forward reference problems do not arise. | the Module Script so that forward reference problems do not arise. | ||
Line 210: | Line 210: | ||
Instances of structures are to be named according to the above rules | Instances of structures are to be named according to the above rules | ||
governing the naming of static and dynamic variables. Instances of | governing the naming of static and dynamic variables. Instances of | ||
structures are commonly created outside the bounds of any | structures are commonly created outside the bounds of any function | ||
and so are static and are named using Camel Notation. | and so are static and are named using Camel Notation. | ||
Line 233: | Line 233: | ||
Normally there will be a "main" structure, defined in the Module | Normally there will be a "main" structure, defined in the Module | ||
Header, having the same name as the module itself. This | Header, having the same name as the module itself. This structure's | ||
name is, of course, in Camel Notation as is the module name. The | name is, of course, in Camel Notation as is the module name. The | ||
names of public members are to be in Camel Notation while the names | names of public members are to be in Camel Notation while the names | ||
Line 260: | Line 260: | ||
The distinction between public and private members is that public | The distinction between public and private members is that public | ||
members are globally | members are globally accessible while private members are accessible | ||
only by other members of the structure. | only by other members of the structure. | ||
Line 275: | Line 275: | ||
</pre> | </pre> | ||
The latter is the | The latter is the preferred method of providing global access to | ||
functions as it is more consistent with the new AGS scripting | functions as it is more consistent with the new AGS scripting | ||
language. As of this writing, static member variables are not | language. As of this writing, static member variables are not | ||
Line 302: | Line 302: | ||
First of all, modules should be as self-contained and independent as | First of all, modules should be as self-contained and independent as | ||
possible. However there are times when it is | possible. However there are times when it is appropriate for one | ||
module to use functions defined in an other module. Such a module is | module to use functions defined in an other module. Such a module is | ||
said to be dependent on the other module. | said to be dependent on the other module. | ||
Line 308: | Line 308: | ||
For example, suppose someone is creating a module that will need to | For example, suppose someone is creating a module that will need to | ||
do extensive database operations to achieve it's purpose. If a | do extensive database operations to achieve it's purpose. If a | ||
general purpose database module is | general purpose database module is available it's probably easier and | ||
better to just use that module rather than replicating the required | better to just use that module rather than replicating the required | ||
database functionality. On the other hand, if only a small portion | database functionality. On the other hand, if only a small portion | ||
Line 318: | Line 318: | ||
If a module is dependent on another module and that module hasn't | If a module is dependent on another module and that module hasn't | ||
been imported into AGS prior to the dependent module, | been imported into AGS prior to the dependent module, compiler errors | ||
will be generated. It will not necessarily be obvious why these | will be generated. It will not necessarily be obvious why these | ||
errors are | errors are occurring. In addition, the dependent module may require a | ||
specific version of a module. So a method of explicitly checking for | specific version of a module. So a method of explicitly checking for | ||
the | the dependency and generating an appropriate error message is clearly | ||
required. This can be done by defining and checking macro definitions | required. This can be done by defining and checking macro definitions | ||
in the Module Header as described below. | in the Module Header as described below. | ||
Line 335: | Line 335: | ||
Each module is also required to have one macro definition named | Each module is also required to have one macro definition named | ||
ModuleName_VERSION defined as the current version number. Each | ModuleName_VERSION defined as the current version number. Each | ||
module is also | module is also required to have one macro definition, for each | ||
released version of the module, named ModuleName_VERSION_XXX, where | released version of the module, named ModuleName_VERSION_XXX, where | ||
XXX is the release version number. An example of this is shown below. | XXX is the release version number. An example of this is shown below. | ||
Line 393: | Line 393: | ||
</pre> | </pre> | ||
These files may be manually prepared or | These files may be manually prepared or programmatically generated by | ||
extracting comments from the Module Script and Module Header and | extracting comments from the Module Script and Module Header and | ||
include the following sections. {note such a document generator is | include the following sections. {note such a document generator is | ||
Line 486: | Line 486: | ||
=== Create Distribution File === | === Create Distribution File === | ||
A module distribution is | A module distribution is comprised of the files listed below. These | ||
files are compressed into a single zip archive for distribution. | files are compressed into a single zip archive for distribution. | ||
Line 529: | Line 529: | ||
module to be redistributed by others (i.e. mirrored on other | module to be redistributed by others (i.e. mirrored on other | ||
websites). To use the LGPL just include the following notice in the | websites). To use the LGPL just include the following notice in the | ||
Module Script, Module Header, and | Module Script, Module Header, and Document. | ||
<pre> | <pre> |
edits