scripting:includes-imports

No renderer 'pdf' found for mode 'pdf'

Includes and Imports

A lot of scripting languages do not support file includes or file imports. There are some workarounds as using of functions like eval in JavaScript or support from hosting applications with use of external configuration files for bundling include files to target source files. And there are really few host applications that support as includes as imports in “like native” way.

HippoEDIT is on of these applications.

To include/import another source file into scope of current file, you should use HippoEDIT specific directives in the beginning of the file:

#include "file1.js" // include file file.js from directory of current file
#import "./../file2.js" // import file2.js from parent directory of current file
// #include "file3.js" // this directive eated but ignored, as commented

The directives should be defined on first lines (empty lines between directives or before do not matter, they will be skipped). HippoEDIT will “eat” this directives, and do not pass to scripting engine. So your scripts works without problems.

The path entered in the directive is relative to the path of the current document.

To comment directive use // as commenting in JavaScript. This comment should be used for directive commenting in any scripting language, while anyway the line with directive will not be passed to the scripting engine.

You can also write your own comments after directive (as in the example) - this is also supported.

HippoEDIT also support patterns in paths of include / import, that you can load a set of files by some pattern using one directive:

#include "tools/*.js"

The code above includes all Java Script files from subdirectory tools. Patterns rules are same as for normal file handling in windows.

If include/import file will not be found in current file directory, HippoEDIT will also search in common script directory, which is located in <user directory>\scripts. The directory initially contain some standard include files that can be used:

  • he_constants.js - auto generated file, which is always included silently in any script, and contains HippoEDIT constants
  • he_utils.js - generic functions, as converting of VB array (you get from HippoEDIT) to JS Array and back
  • he_edit.js - generic functions for document editing

Imports are nothing more than inserting of source code from import file to scope of the main source file. Independently of there you place import directive, HippoEDIT will insert code at beginning of file, but taking into account inclusion sequence.

You can, of course, import one or more files and have embedded imports (you import one file and it imports another file etc). If you will have circle references in embedding sequence, HippoEDIT will try to solve it.

As example:

imp1.js
var a = 1;
imp2.js
var b = a + 1;
imp3.js
#import "imp2.js"
var c = b + 1;
example.js
#import "imp1.js"
#import "imp3.js"
Output().writeln("c = " + c);

will output:
c = 3

Includes in contrast to imports, are stand alone scripting objects with their own objects scope. Inside of the include, you objects are only see declarations of functions/objects from their includes, but not from the parent as imports can do.

Advantages of include files are:

  • more clear scope logic
  • performance is better than with imports
  • you can include file in another scripting language and would work (so you can include in JavaScript files, VB Script files for example).

As with import files, you need to write include directive in the beginning of the script file. The sequence of inclusion considered.

Here is small usage example:

inc1.js
var a = 1;
// a += d; - this will fail (access of parent file scope)
inc2.js
var b = 2;
inc3.vbs
#include "inc2.js"
Dim c
c = b + 1
example.js
#include "inc1.js"
#include "inc3.vbs"
var d = 5;
Output().writeln("c = " + c);
Output().writeln("a = " + a);

will output:
c = 3
a = 1