Using Them

The import system in Simkey allows you to import functions both from the main simkey-imports directory (under the main Simkey directory), and from anywhere else you define an Importable function. It also allows you to alias the functions when importing them.

note

Keep in mind that you can also define .autoimport files within any directory that follows the same importing rules. Every simkey file under that directory will have all those imports automatically accessible.

If you are working on a file outside of said directory, you can still import this .autoimport file, using it to bundle together the imports conveniently.

Handling import paths

There are three ways of importing a file. The first way is to import a file from within the simkey-imports directory.

The simkey-imports directory is where the built-in functions are (under simkey-imports/std) and you can find it in your Simkey App/src/simkey folder in the AppData assuming you are on Windows (Win+R then %appdata%Simkey App/src/simkey).

Another way is to import relative to the directory of your Simkey file, and the last way is through using an absolute path.

Regardless of which method, the path always ends in a JS file without the file extension .js at the end. These imports are done under the IMPORTS section, or within a .autoimport file.

For now we will be putting an @ behind all of these paths, and the name will automatically be set to the name of the JS file. If you want to alias the function, go to the last section of this page.

From the simkey-imports directory

Importing from within the simkey-imports is the default. In order to do it, simply write out the name of the JS file. If you want to import from some directory within, type out the directories name and traverse as you would normally using front slashes.

Assuming the simkey-imports directory looks like this:

simkey-imports
├── std
│   └── ...
├── my_dir
│   └── abc.js
└── test.js

To import test.js and abc.js in a Simkey file, you can do this:

<IMPORTS>
    @test
    @my_dir/abc

You cannot go backwards relative to the simkey-imports directory, you can only go further in.

Relative to the Simkey file

You can use a path relative to your Simkey file by making use of ./. In order to import your current directory, you can do ./file. If it is from the directory above yours, you can do ../file. Another directory above would be ../../file, and so on.

If you start with a /, it will be interpreted as an absolute path. You must start with either ../ or ./. These are the same conventions used when importing a CommonJS or ES module in JavaScript.

Here's how you can go about it in this example:

dir
├── first
│   └── abc.js
├── second
│   └── def.js
├── test
│  ├── jkl.js
│  └── run.simkey
└── ghi.js

<IMPORTS>
    @../first/abc
    @../second/def
    @../ghi
    @./jkl

Absolute paths

To use an absolute path, you can either simply start with a /, which will be treated as an absolute path from whatever drive your file is in if you are on Windows, or include your drive in the path (ex. C:/my_dir).

Otherwise, as expected, absolute paths start with / either way when on Mac or Linux.

Aliasing an Importable function

Giving an alternative name from the name of the JS file itself, you simply separate the @ from the path, and type out whatever name you want, keeping in mind potential conflicts.

Here's the example from the simkey-imports directory:

simkey-imports
├── std
│   └── ...
├── my_dir
│   └── abc.js
└── test.js

<IMPORTS>
    @my_func test
    @my_func_2 my_dir/abc

.autoimport and CALL.BEFORE functions

These are two cases that importing is done a little differently in. They both don't have a name that starts with @.

Importing a .autoimport

You only need to consider this when your file is not already in the same directory as the .autoimport file.

To import the file in that case, have the path to the directory (in whatever one of the three methods you want from above), then add a /* to the end.

For example here's how you would handle this case:

dir
├── first
│   └── test.simkey
└── .autoimport

<IMPORTS>
    ../*

Using a CALL.BEFORE function

As a refresher, a CALL.BEFORE function is an Importable function that gets called before the Simkey file is parsed, allowing it to make changes beforehand or go through its own parsing step. To import a CALL.BEFORE function, you write out "CALL.BEFORE" followed by the path formatted in the same ways as above.