Difference between revisions of "Import"

From MiniScript Wiki
Jump to navigation Jump to search
Line 3: Line 3:
 
[[env]].importPaths.  <c>import</c> looks for a file with the module name plus ".ms".
 
[[env]].importPaths.  <c>import</c> looks for a file with the module name plus ".ms".
 
Any values defined by that code then become available in a map of the same name.   
 
Any values defined by that code then become available in a map of the same name.   
 +
 +
== Usage Notes ==
 +
 +
<c>import</c> imports the named module into the current local variable space.  Simple (and typical) usage is to do this at the top of your main program, where [[locals]] and [[globals]] are the same thing, which makes the imported module globally available.
 +
 +
However, if you have a large, complex project composed of many interdependent modules, '''and''' you want those various modules to be testable on their own, then those modules are likely to be importing other modules, in what can rapidly become a tangle of imports that leads to several problems:
 +
 +
# A recursive cycle of imports (e.g. A imports B which imports A) can result in an infinite loop.
 +
# Importing a large module several times wastes time and makes your program take longer to load than necessary.
 +
# If the module has any internal state, then you now have multiple separate copies of that internal state, which can lead to hard-to-find bugs.
 +
 +
The solution to all these problems is to make a function like the following:
 +
 +
<ms>// ensureImport: check whether the given module has been imported already
 +
// (or is in the process of being imported).  If so, return immediately.
 +
// If not, then import that module into the global namespace.
 +
globals.ensureImport = function(moduleName)
 +
if globals.hasIndex(moduleName) then return
 +
globals[moduleName] = "PENDING" // (module is being imported now)
 +
import moduleName
 +
globals[moduleName] = locals[moduleName]
 +
end function</ms>
 +
 +
Put this in some tiny, stand-alone script that can be safely imported from anywhere.  Import this with <c>import</c>, but then load all other modules with the <c>ensureImport</c> function it provides.  For example, if the above function is in a script called "coreUtils":
 +
 +
<ms>import "coreUtils"
 +
ensureImport "someModule"
 +
ensureImport "someOtherOne"</ms>
 +
 +
This will ensure that no matter how your various files depend on each other, each one is only loaded once.
  
 
== Examples ==
 
== Examples ==

Revision as of 16:19, 17 July 2021

import is a Mini Micro function that loads a MiniScript file from the current directory, /sys/lib, /usr/lib, or some path defined in env.importPaths. import looks for a file with the module name plus ".ms". Any values defined by that code then become available in a map of the same name.

Usage Notes

import imports the named module into the current local variable space. Simple (and typical) usage is to do this at the top of your main program, where locals and globals are the same thing, which makes the imported module globally available.

However, if you have a large, complex project composed of many interdependent modules, and you want those various modules to be testable on their own, then those modules are likely to be importing other modules, in what can rapidly become a tangle of imports that leads to several problems:

  1. A recursive cycle of imports (e.g. A imports B which imports A) can result in an infinite loop.
  2. Importing a large module several times wastes time and makes your program take longer to load than necessary.
  3. If the module has any internal state, then you now have multiple separate copies of that internal state, which can lead to hard-to-find bugs.

The solution to all these problems is to make a function like the following:

// ensureImport: check whether the given module has been imported already
// (or is in the process of being imported).  If so, return immediately.
// If not, then import that module into the global namespace.
globals.ensureImport = function(moduleName)
	if globals.hasIndex(moduleName) then return
	globals[moduleName] = "PENDING"	// (module is being imported now)
	import moduleName
	globals[moduleName] = locals[moduleName]
end function

Put this in some tiny, stand-alone script that can be safely imported from anywhere. Import this with import, but then load all other modules with the ensureImport function it provides. For example, if the above function is in a script called "coreUtils":

import "coreUtils"
ensureImport "someModule"
ensureImport "someOtherOne"

This will ensure that no matter how your various files depend on each other, each one is only loaded once.

Examples

The following example loads a script called "mathUtil.ms" (normally found in /sys/lib), and makes it available as a map called mathUtil.

import "mathUtil"
print mathUtil.radToDeg(2*pi)  // prints 360

Some modules, like listUtil, stringUtil, and mapUtil, extend these built-in types with new methods. For example, the built-in list type does not have a .reverse method, but it does once you import "listUtil":

import "listUtil"
print [1,2,3].reverse  // prints [3, 2, 1]