HSP : Hot Soup Processor ver3.6 / onion software 1997-2021(c)

HSP3 Module Function Guide

1. About HSP module function
2. About user-defined instructions
3. How to use the module (basic)
4. How to use the module (application)
5. Module definition instruction
6. About the module cleanup function
7. Standard keywords and "@hsp" module names

This text is supported by Hot Soup Processor ver3.0 or later Contains a description of module functionality.

Modular function is for those who want to use HSP deeper and more advanced. This is an extension. However, this feature is not necessary for everyone. For beginners and those who are going to use HSP, they haven't learned about modules yet. You don't have to. However, intermediate and above are more efficient at source It is an important element that can be reused, so please master it.

In addition, advanced users can take advantage of more advanced module variable functions. The details of module variables are not covered in this guide, so See the programming guide for more information.

About HSP module function

The module function allows multiple scripts without worrying about label name or variable name collisions. It is a mechanism for combining.

This function manages a large number of variable names when creating large-sized scripts. It is effective when you do. By utilizing the module function You will be able to create more versatile scripts.

Also, even if you don't use the module function, other people can use the module function. It is possible to use the new instructions added using. This is due to the DLL It is the same as the mechanism of the extension plug-in.

First, let's talk about modules. For example, let's say you have a source script called "test1.as". Suppose you are using variables a and b in this source script. If another person created a source script called "test2.as", there What if you had a very useful subroutine? If you don't use the names variable a and variable b in "test2.as", there is no problem. You may be able to bring just the subroutine as it is. However, if "test2.as" also uses variable a and variable b for different purposes, It's very troublesome.

If you use the HSP module function, you can create a script from "test1.as" to "test2.as". It will be possible to call it, but it is used in "test1.as" and "test2.as" Variables that are present are treated as independent (even if they have the same name). Also, register the subroutine in this independent script as a new instruction. It is possible to pass and receive parameters.

Reuse modules created in the past, publish them for people to use, Wider application of HSP scripts, such as using modules created by someone else It will be possible to do.

To master the HSP module, user extension instructions, module in You need to use port instructions etc. These are also convenient as a single unit An instruction that provides a function. Don't try to remember at once, one from what you know Let's master one.

About user-defined instructions

User-defined instructions are one of the instructions added with the HSP module function. The user can add an instruction with a new name at will. This is very powerful even if it is used alone apart from the HSP module function. Will be.

User-defined instructions are used as follows.

    goto *main

#deffunc routine
    mes "sub-routine"
    return

*main
    routine
    stop

There is no "routine" in HSP instructions, so until now it was an error However, when I actually execute this script, it says "sub-routine". Is displayed and the command "routine" is executed.

User-defined instructions can be defined by the instruction "#deffunc". #deffunc instruction name Will add an instruction with a new name. After that, if a new command comes out, go to the place where "#deffunc" is. Subroutine jump. In other words

    goto *main

*routine
    mes "sub-routine"
    return

*main
    gosub *routine

Even with a script like

    goto *main

#deffunc routine
    mes "sub-routine"
    return

*main
    routine

But it's the same.

Also, user-defined instructions can pass parameters to subroutines. It is possible.

    goto *main

#deffunc routine int prm1, int prm2
    mes "Parameter 1 is" ​​+ prm1 + "."
    mes "Parameter 2 is" + prm2 + "."
    return

*main
    routine 10,20

In the conventional gosub instruction, when passing a value to a subroutine, it is done in advance. I had no choice but to put a value in a fixed variable and call it. User-defined instructions instead pass values ​​in a smart way It is possible.

Also, the parameters to be passed are not only numerical values, but also character strings, variables (arrays), etc. There are many variations. Also, when returning from a subroutine Assign a value to the system variable stat or to a variable specified as a parameter It is also possible to write back the value.

This parameter, also known as an alias, is indicated by the #deffunc instruction. It can be set when defining a new instruction.

 #deffunc Instruction name Parameter type alias name,… 

By writing as, to get the specified parameter type, You will be able to refer to it by alias name. For more information, see #deffunc instruction details.

Also, from HSP3.0, the user can define the function with the #defcfunc instruction. It is possible. This is also the same specification as the #deffunc instruction, and you can easily create a function. You can add it.

How to use the module (basic)

A module is a source unit that can handle variable names and label names independently. The easiest way to use a module is to have one module part Save it as a source script file (as file) and start from another file Is to call it as a module. For example, write the module source in a file called test1.as.

 // Contents of test1.as

#module
#deffunc test1
    mes "Displayed in test1.as."
    return
#global

Modules always start with "#module" and end with "#global" Think of it as a promise.

If you write it like this, it will be called by the instruction "test1" in the module. You will have a subroutine that you can do. Next, put the source to call this in a file called "test2.as" Let's write.

 // Contents of test2.as

#include "test1.as"
    mes "test2.as."
    test1
    stop

Source "test1.as" for registering a module with the "#include" instruction Now loading.

After this, you will see a line with the command "test1". Since this is a user-defined instruction (for details, see "About user-defined instructions". (See), the subroutine "test1.as" is called. When you actually run this script,

 test2.as.
It is displayed in test1.as. 

Two lines appeared, and the module of test1.as was called from test2.as. I understand this.

In this basic example, we are only displaying a message, so we use the gosub instruction. It hasn't changed much from the subroutine call, and its power as a module is It has not been demonstrated. But what about the following example?

 // Contents of test1.as

#module
#deffunc test1
    a=456
    mes "In test1,"
    mes "A =" + a + "."
    return
#global

 // Contents of test2.as

#include "test1.as"
    a=123
    test1
    mes "In test2,"
    mes "A =" + a + "."
    stop

Now when I run "test2.as",

 in test1
A = 456.
In test2
A = 123. 

It will be. Normally, 456 is assigned to the variable a first on the "test1.as" side. Since it is, the same value is obtained in "test2.as", but the module Since the names are independent inside and outside, even with the same variable a, "test1.as", "Test2.as" keeps different contents.

In this way, even if the names of variables and labels are duplicated, there is no problem at all. The basic concept of the module is that each script works is.

However, there are some problems when variables are independent. Call the module Sometimes you want to get some result, or you want to pass a value to a module.

Actually, the function for this is prepared in the user-defined instruction, and another mod It can be used to exchange parameters with the tool.

 // Contents of test1.as

#module
#deffunc test1 int prm1
    mes "The parameter is" + prm1 + "."
    return 1
#global

 // Contents of test2.as

#include "test1.as"
    a=543
    test1 a
    mes "STAT is" + stat + "."
    stop

In the above example, the call to the user-defined instruction test1 is called "test1 a". In the description with parameters, the content of variable a, the value 543, is passed. In "test1.as", this passed value is given by the alias name prm1. Fetch it, assign the value 1 to the system variable stat, and exit.

The important thing is that in "test2.as" the variable name used in "test1.as" And so on, you don't have to worry about it. Similarly, from "test1.as", the variable name with the caller overlaps. You don't have to worry about it. Subroutines with independent functions can be completely separated It is an HSP module function.

The above is the basic usage of the module. See the next section for further applications.

How to use the module (application)

In the basic explanation, only one instruction was defined in one module, You can also create multiple user-defined instructions in one module.

 // Contents of test1.as

#module
#deffunc test1
    mes "Displayed by test1"
    return

#deffunc test2
    mes "Displayed by test2"
    return
#global

In the above example, the new instructions "test1" and "test2" are added. In this case, the variable name and label name are the same between "test1" and "test2". Become.

If you want to use independent variable names and label names for "test1" and "test2",

#module
#deffunc test1
    mes "Displayed by test1"
    return
#global

#module
#deffunc test2
    mes "Displayed by test2"
    return
#global

This can be achieved by writing in this way. In other words, a module is a section separated by "#module" to "#global". I am instructing you to think of the other sections as a completely different world. That's what it is.

In the basic explanation, there are two files, "test1.as" and "test2.as". Explain the module and the other part (global area) separately I was there. In fact without including "test1.as" It is possible to create more and more modules in one file, but If possible, use only one module in one file and one source It is better to unify the variable name and label name in the script. Especially for label names, there are many same labels in one source script. It can be confusing.

All variables in a module are basically shared statically. In other words, a variable once set loses its contents unless another value is assigned. It is not. Therefore, recursive call (calling itself) Be careful when doing.

Within each definition instruction, a local declaration explicitly sets a local variable. You can create it. When making a recursive call, be sure to do it internally Make sure the variables you use are local. (If you make a local declaration, it's more than usual to create and destroy variables. Also keep in mind that there is a cost to run. )

Module definition instruction

The following preprocessor instructions are provided as module definition instructions in HSP3.

• #module
• #global
• #deffunc
• #defcfunc

Check the usage of each instruction from the help browser.

About the module cleanup function

The cleanup function is a script in the module just before the HSP program ends. It is called automatically, and after that, when the function is expanded by a module, etc. It allows you to release the system and memory. This is a cleanup function calling. To use this feature, when declaring a user-defined instruction in a module,

 #deffunc name onexit 

Please put "onexit" in the part that describes the argument like. When the HSP program is finished, the instruction is automatically executed. However, note the following points within this instruction:

• End, stop, wait, await, dialog, and other instructions that cause a time wait cannot be used
• Commands such as mes that are output to the screen do not work

In other words, only the final work such as releasing the minimum memory and calling the external DLL Think of it as a description. There is a onexit instruction that works in the same way, but as a system process

1. [Interrupt HSP program]
2. [Execute the jump destination of the onexit instruction]
3. [Run module cleanup destination]
4. [Complete destruction of HSP resources]

It is in the order. At the jump destination of the onexit instruction, it is also possible to interrupt the program itself. Yes, but you can't interrupt the cleanup feature. Also, if multiple modules or multiple cleanup instructions are registered, It will be executed one after another by following the order in which it was registered.

Standard keywords and "@hsp" module name

Standard keywords are assigned to the space with the module name "@hsp". This means that the name "mes @ hsp" is the official name for the mes instruction, for example. However, names without "@hsp" are also registered as aliases so that they can be used in normal global spaces. You can use it as it is with the same instruction name as before.

For example, for the mes instruction, "#define global mes mes @ hsp" is the same as being defined from the beginning. (After preprocessor processing, standard keywords are expanded to canonical names with "@hsp". You can see it by opening "hsptmp.i" which can be output at compile time depending on the settings. )

As a result, the name itself registered as a standard keyword can be used as an alias. Allows the user to redefine. The following is an example of replacing the mes instruction with a macro.

#undef mes
#define mes(%1) mes@hsp "MES->"+%1
    mes "Message." // "MES- & gt; Message." Is displayed.
    stop

The keyword "mes" is redefined after being canceled by the #undef instruction. All standard keywords used by HSP can be canceled and redefined as well.

The following is an example of replacing the mes instruction with a user-defined instruction.

#undef mes
#module
#deffunc mes str _p1
    _y = ginfo_cy

    color 0, 0, 0
    pos ginfo_cx+1, _y+1
    mes@hsp _p1

    color 0, 192, 255
    pos ginfo_cx, _y
    mes@hsp _p1
    return
#global
    mes "I tried to make the mes instruction a shadow character." 

Use the standard keyword redefinition with caution as it affects all subsequent keywords.

• Return to top of this page
• Return to list of documents
• Go to HSPTV page