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 moduleand usemethod to declare and use reusable modules.
1. Module introduction
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
module moduleNamestarts with the statement module statement - 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 system configuration parameters homeand 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 under this directory to save the module files, and 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 moduleNamemoduleName must be consistent with the name of the module file, for example, declare the module in FileLog.dos:
module FileLogAfter 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 usekeywords 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::DateUtil4.2 Call the namespace module
We can useadd the full path after the keyword to import the module under 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 debug 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 useimported directly on the DolphinDB of the remote server. The module file needs to be uploaded to the corresponding directory of [home]/modules before it can be passed. useCall the module.
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 complete, you can directly execute the useimport module.
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, if you need to repeatedly modify the module code and refresh the definition, you only need to re-execute the code in the module file. This method is only valid for the current session.
6.3 Mutual calls between modules
Modules can be referenced in one direction. For example, module a refers to module b, and module b refers to module c. Cross reference is not supported. For example, module a refers to module b, and module b refers to module a.