fn: script
[contents]

#### Syntax

The syntax for script calls is:

f++:
script{options}(params)


n++:
@script{options}(params)


#### Description

The script function is for running scripts/programs, it takes a non-zero number of parameters, the first parameter is the name or path of the script/program to run and the remaining parameters are input parameters for the script/program.

Note: Scripts/programs run with @script calls are moved to the project root directory to run and have a backup copy made. If scripts/programs are so large that copying the file will take time, or you are making lots of calls which is slower at scale, you can use the !bs option to not have the script backed up, eg.:

@script{!bs}('./script.py')


Note: If you need to have different files/threads running the same script during the build process you will either need to set the number of build threads to 1 or put up with having to rebuild on the occassions where Nift unsuccessfully tries to run both scripts at the same time. You can always have duplicate copies of the same script in different files and have each file/thread run a different version.

Note: Scripts and system calls are run from the project root directory so all paths in your scripts should start from there. Also do not change directory in your scripts as it will mess up the other threads that are also building output files (this is an unfortunate limitation of C++). If you really must change directories in your scripts then you can take a reduction in build times and set the number of build threads to 1, make sure to change back to the project root directory before each script ends.

Note: script calls do not scale very well to hundreds of thousands of calls, it is much better to combine as much as possible in to as few script/system calls as possible for very large projects (moving stuff to the pre/post build scripts is the best place, you can output stuff to file and process the files when building). For example if possible it is much faster to have a few pre-build scripts to download text from multiple urls using cURL, and/or make all the api calls, all the database queries, and work on JSON data needed and distribute the needed output in to different files to be inputted when needed. Note that file-specific build scripts have the benefit of running in parallel to each other, whereas project-wide build scripts do not.

#### Options

The following options are available for script calls:

option description
b or block call is followed by a code-block to save to the script path for running
pb parse code-block following call before saving to script path for running
!bs do not backup script
content add content file path of file being built as first input parameter to script/program
console print script output to console
if-exists do not throw an error if the script does not exist
inject inject in to file being built after parsing with language call is made from
!o do not add script output to file being built
raw inject in to file being built raw
!ret do not return script/program return value
option description

#### f++ example

Examples of script being used with f++:

script("pre-build.rb")

script{b}("pre-build.py")
{
print("hello, world!")
}

#### n++ example

Examples of script being used with n++:

@script("pre-build.rb")

@script("./script.py", "light blue", "red")

@script{b}("pre-build.py")
{
print("hello, world!")
}