DolphinDB module reuse tutorial

In a software team development project, to improve development efficiency and quality, code must be packaged and reused. When using DolphinDB scripts for development, you can use the module and use methods to declare and use reusable modules.

1. Introduction to Module

In DolphinDB, a module refers to a code package that only contains function definitions. It has the following characteristics:

• Use .dos as the suffix of the module file, dos is the abbreviation of "dolphindb script"
• The module file is stored in the [home]/modules directory of the DolphinDB node
• The first line of the module file starts with the statement module moduleName
• The content of the module file only contains function definitions

2. Define the module

2.1 Create a module directory

By default, all modules are defined in the [home]/modules directory. [home] is determined by the system configuration parameter home, which can be obtained through the getHomeDir() function. For example, the home directory of the DolphinDB node is:

/root/DolphinDB/server

Then we need to create a modules subdirectory in this directory to save the module files. The final module directory is:

/home/root/DolphinDB/server/modules

2.2 Create a module file

Create a module file with a suffix of .dos in the modules directory, such as FileLog.dos. The first line of the module file must be a module declaration statement. The syntax of the module declaration statement is as follows:

module moduleName

moduleName must be consistent with the name of the module file, for example, declare the module in FileLog.dos:

module FileLog

After declaring the module, we can start writing the module code. For example, the content of FileLog.dos is as follows:

module FileLog
//向指定日志文件写入日志
def appendLog(filePath, logText){
	f = file(filePath,"a+")
	f.writeLine(string(now()) + " : " + logText)
	f.close()
}

In the module file, only encapsulated function definitions are allowed, and other non-function definition codes will be ignored .

3. Import the module

In DolphinDB, use the use keyword to import a module. Note that the module imported by the use keyword is session isolated and only valid for the current session. After importing the module, we can use the custom functions in the module in the following two ways:

(1) Use the functions in the module directly:

use FileLog
appendLog("mylog.txt", "test my log")

(2) Call the function in the module through the complete path:

use FileLog
FileLog::appendLog("mylog.txt", "test my log")

4. Planning Module

DolphinDB introduces the concept of namespaces and supports the classification and planning of modules.

4.1 Declare the module namespace

If we need to classify modules, we can use multi-level paths to plan the module's namespace. For example, there are two existing modules, FileLog and DateUtil, and their storage paths are modules/system/log/FileLog.dos and modules/system/temperal/DateUtil.dos respectively. Then the corresponding declaration statements for these two modules are as follows:

• modules/system/log/FileLog.dos

module system::log::FileLog

• modules/system/temperal/DateUtil.dos

module system::temperal::DateUtil

4.2 Call the namespace module

We can add the full path after the use keyword to import modules in the namespace. For example, import the FileLog module:

use system::log::FileLog
//全路径调用
system::log::FileLog::appendLog("mylog.txt", "test my log")
//直接调用已导入模块中的函数
appendLog("mylog.txt", "test my log")

5. Remote debugging module in GUI

When the working machine and the DolphinDB server are not the same machine, the module code we edited on the working machine cannot be directly imported through use on the DolphinDB of the remote server. You need to upload the module file to the corresponding directory of [home]/modules first. Call the module through use.

DolphinDB GUI has provided the function of remote synchronization module since version 0.99.2. The specific usage is shown in the figure below:

This operation will synchronize all files and subdirectories in the Modules directory to the [home]/modules directory of the DolphinDB node connected to the GUI. After the synchronization is completed, you can directly execute the use code to import the module on the Server.

6. Matters needing attention

6.1 Definition rules for functions with the same name

Different modules can define functions with the same name. If you use the full path to call the function, DolphinDB can distinguish the function name through the module namespace. If you call the function directly:

• If only one of the imported modules contains this function, DolphinDB will call the function of this module.
• If multiple modules in the imported module contain this function, DolphinDB will throw the following exception when parsing the script:

Modules [Module1] and [Module2] contain function [functionName]. Please use module name to qualify the function.

• If the imported module has the same name as the custom function, the system will use the function in the module by default. If you want to call a custom function, you need to declare the namespace. The default namespace of custom functions and built-in functions is the root directory, which is represented by two colons. such as:

//定义模块
module sys
def myfunc(){
 return 3
}

//自定义函数
login("admin","123456")
def myfunc(){
 return 1
}
addFunctionView(myfunc)

//调用
use sys
sys::myfunc() //调用模块的函数
myfunc() //调用模块的函数
::myfunc() //调用自定义函数

• If the function is not included in the imported module, DolphinDB will search for the function in the system built-in functions. If there is no such function in the built-in function, it will throw the exception defined as the function.

6.2 Refresh module definition

When debugging the module code in the development phase, the developer needs to repeatedly modify the module code and refresh the definition. At this time, you can reopen the module file and select all the module codes to execute. This method is only valid for the current session.

6.3 Calling each other between modules

One-way references can be made between modules, for example, module a refers to b and b refers to c. Cross-references are not supported between modules. For example, module a refers to b, and module b refers to a.