In software team development projects, to improve development efficiency and quality, the code must be encapsulated and reused. When developing with DolphinDB scripts, the Module and use methods can be used to declare and use reusable modules.

1. Introduction to Module

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

  • Module files are suffixed with. DOS, which is short for “Dolphindb Script”
  • The module files are saved in the [home]/modules directory of the DolphinDB node
  • The first line of the module file begins with the declaration module statement Module moduleName
  • The module file content contains only function definitions

2. Define modules

2.1 Creating 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
Copy the code

So we need to create modules subdirectory in this directory to save the module file, the final module directory is:

/home/root/DolphinDB/server/modules
Copy the code

2.2 Creating a Module File

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

module moduleName
Copy the code

ModuleName must match the name of the module file, such as declaring the module in filelog.dos:

module FileLog
Copy the code

With the module declared, we can start writing module code. For example, filelog. DOS is as follows:

Def appendLog(filePath, logText){f = file(filePath,"a+") f.riteline (string(now()) +" : " + logText) f.close() }Copy the code

In the module file, only function definitions are allowed to be wrapped; other non-function definition code is ignored.

3. Import the module

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

(1) Directly use functions in the module:

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

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

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

4. Planning module

DolphinDB introduced the concept of namespaces and supported module classification and planning.

4.1 Declaring the Module namespace

If we need to categorize modules, we can plan the namespace of modules through multi-level paths. For example, the existing two modules FileLog and DateUtil, their repository paths respectively modules/system/log/FileLog DOS and modules/system/temperal/DateUtil DOS, The corresponding declarations 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 Calling the namespace module

We can import modules in the namespace by adding the full path after the use keyword. For example, importing the FileLog module:

Use system: : log: : FileLog / / the full path call system: : log: : FileLog: : appendLog (" mylog. TXT ", AppendLog ("mylog.txt", "test mylog ");Copy the code

5. Remote debugging module in GUI

When DolphinDB and DolphinDB servers are on different machines, module code edited on the machine cannot be imported from the remote server through use. You must upload the module file to the corresponding directory of [home]/ Modules before invoking the module through use.

The DolphinDB GUI provides remote synchronization modules from version 0.99.2, as shown below:

This synchronizes all files and subdirectories in the Modules directory to the [home]/ Modules directory on the DolphinDB node connected to the GUI. When this is done, you can import Modules directly from the Server by executing the use code.

6. Precautions

6.1 Defining rules for functions with the same name

Different modules can define functions with the same name. DolphinDB allows function names to be distinguished by the module namespace if functions are called in a full path. If you call the function directly:

  • DolphinDB calls DolphinDB functions when only one of the imported modules contains the function.

  • DolphinDB will throw an exception when it parses a DolphinDB script if more than one of the imported modules contains this function:

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

  • If an imported module has the same name as a user-defined function, the system uses the functions in the module by default. If you want to call custom functions, you need to declare a namespace. The default namespace for custom and built-in functions is the root directory, denoted by two colons. Such as:

    Sys def myfunc(){return 3}

    Def myfunc(){return 1} addFunctionView(myfunc)

    // Call use sys sys::myfunc() // Call module function myfunc() // Call module function ::myfunc() // call custom function

  • DolphinDB searches for the function in the system built-in functions if it is not included in an imported module. If the built-in function also does not exist, the function is thrown as the defined exception.

6.2 Updating the Module definition

When debugging the module code during the development phase, the developer needs to modify the module code repeatedly and refresh the definition. In this case, the developer can reopen the module file and execute the module code completely. This method is only effective for the current session.

6.3 Modules Call Each other

Modules can reference each other in one direction, for example, module A refers to B, and B refers to C. Cross-references between modules are not supported. For example, module A references module B, and module B references MODULE A.