diff --git a/Modules-overiew.md b/Modules-overiew.md new file mode 100644 index 0000000..6a97c7f --- /dev/null +++ b/Modules-overiew.md @@ -0,0 +1,24 @@ +SMNP comes with predefined functions and methods which all makes up the _standard library_. +In contrast to Python-based SMNP version, standard library has been split into several standalone _*.jar_ files, which are called _modules_. All available _modules_ are dynamically collected just before SMNP interpreter invocation, so that the interpreter knows about them. When it comes to handle `import` statement, the module canonical name is being consumed and basing on that, a proper module from module registry is loaded into evaluation environment. From now on all functions and methods contained in the module are available and ready to be executed. + +# Module structure +Technically, _module_ is an object that represents a node in the tree-like structure, which can contain methods, functions and children - submodules. Thanks to that, modules can be arranged into the logical structure, for example, all audio-related staff can have common parent: `audio`, which is also a child of `smnp` root package that contains entire standard library. Note, that importing some module, for example `smnp.music` **will not** import its children. You need to provide canonical name (full path from root to desired node) of each module you want to make use of. + +# Module provider +Each _*.jar_ file contained in modules directory has to extend `ModuleProvider` class and mark it with `@Extension` annotation (which comes from _PF4J_ plugin framework). The `ModuleProvider` is an object that is responsible for instantiating and providing ready for use _Module_ object. +SMNP out-of-the-box provides 2 `ModuleProvider` abstract subclasses that are ready to be extended by external modules definitions: +* `LanguageModuleProvider` +* `NativeModuleProvider`. + +## `LanguageModuleProvider` +The `LanguageModuleProvider` allows you to define custom methods and functions indirectly in SMNP language. +All you have to do is to override `files()` method to return a list of names of files contained in `resources/` directory. If you have only one file, you can leave the function to return default value, which is a list with single item: `main.mus` string. + +The `LanguageModuleProvider` uses a cut interpreter version, which allows your scripts to have only functions and methods definitions at the top-level of script - even `import` statements are disallowed. Dealing with required dependencies is described in next part of the section. + +## `NativeModuleProvider` +The `NativeModuleProvider allows you to implement some functionalities that are not available indirectly in SMNP language. For example, if you need to introduce new audio engine, you would prefer to do it _natively_ in JVM-backed language and provide a _binding_ to SMNP language. This kind of module providers make SMNP language flexible and allows extending and adapting to totally new requirements. + +# Dependencies +Each module can define custom functions and methods which requires other ones that are already defined in other modules. To resolve the problem, SMNP allows modules to declare their dependencies list which is a list of canonical names of each needed modules. When it comes to load the module, SMNP interpreter will also load all its dependencies if they are not already loaded. +In both `LanguageModuleProvider` and `NativeModuleProvider` it can be done simply by overriding `dependencies()` method to return a list of its dependencies' canonical names. \ No newline at end of file