Imports

Let's unravel the art of importing files and libraries in FatScript! Why? Well, because in this language you can import whenever your heart desires, simply by using a left arrow <-.

Dot syntax

To use imports with dot syntax, the name of project files and folders should not start with a digit or contain symbols.

you can force any path you like by using literal paths

Named import

To import files, use the .fat extension for filenames (or no extension at all), but omit the extension in the import statement. Here's an example:

ref <- filename

if both x and x.fat files exist, the latter takes precedence

To import files from folders, use the following syntax:

ref1 <- folder.filename
ref2 <- folder.subfolder.filename

To import all files from a folder, use the dot-underscore syntax:

lib <- folder._

Note that only files immediately inside the folder will be included with this syntax. If you need to include files from subfolders, you must explicitly include those.

Additionally, you can add a "_.fat" file (or "_" file) inside a folder to override the dot-underscore import behavior.

Element access

After importing, you can access elements with dot syntax as well:

ref1.element1

Element extraction

If you only need specific elements from a named import or prefer not to always prepend the module name when accessing those e.g. lib.foo, you can use destructuring assignment to extract them to the current namespace:

{ foo, bar } = lib

Local import

You can also do imports to the current scope using underscore, like so:

_ <- filename

Local imports differ from named imports in that the content of the file is directly "dumped" into the current scope. This means that you can call an imported method directly, like baz(arg), instead of using ref.baz(arg).

While local imports are best suited for importing types into the global scope, they should be used with caution when importing library content. Overusing local imports can lead to namespace pollution, which can make it more challenging to follow the code, because it becomes less apparent where the methods come from.

Literal paths

With literal paths, you may use any filename or extension. However, note that those imports are not evaluated during bundling, but at runtime. Here's an example:

ref <- '_folder/2nd-source.other'

You can also use smart texts as literal paths:

base = 'folder'
file = 'source.xyz'
ref <- '{base}/{file}'

Since FatScript alternatively accepts JSON-like syntax you may even load a JSON file directly as an import:

json <- 'sample/data.json'

Keep in mind that literal paths can make your code more complex, and those imports can only be dynamically resolved, so use them sparingly.

Import policy

FatScript follows an "import once policy" that sets a flag in the current scope to prevent importing the same file multiple times. If an import statement is encountered for a file that has already been imported, it is transparently skipped over.

However, if you import a file within a method body, the import statement will execute each time the method is called.