= kscript - Having fun with Kotlin scripting

image:https://img.shields.io/github/release/kscripting/kscript.svg[GitHub release,link=https://github.com/kscripting/kscript/releases] image:https://github.com/kscripting/kscript/actions/workflows/build.yml/badge.svg[Build Status,link=https://github.com/kscripting/kscript/actions/workflows/build.yml] image:https://badges.gitter.im/kscripting/kscript.svg[Gitter,link=https://gitter.im/kscripting/kscript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge]

Enhanced scripting support for https://kotlinlang.org/[Kotlin] on *nix-based and Windows systems.

Kotlin has some built-in support for scripting already, but it is not yet feature-rich enough to be a viable alternative in the shell.

In particular this wrapper around kotlinc adds

• Compiled script caching (using md5 checksums)
• Dependency declarations using gradle-style resource locators and automatic dependency resolution
• More options to provide scripts including interpreter mode, reading from stdin, local files or URLs
• Embedded configuration for Kotlin runtime options
• Support library to ease the writing of Kotlin scriptlets
• Deploy scripts as stand-alone binaries

Taken all these features together, kscript provides an easy-to-use, very flexible, and almost zero-overhead solution to write self-contained mini-applications with Kotlin.

Good News: Kotlin https://kotlinlang.org/docs/reference/whatsnew14.html#scripting-and-repl[v1.4] finally ships with a much improved - and needed - scripting integration. See https://github.com/Kotlin/kotlin-script-examples/blob/master/jvm/main-kts/MainKts.md[here] for examples and documentation. Still, we think that kscript has various benefits compared this new platform-bundled improved toolstack, so we'll plan to support kscript until the kotlin platform will ship with an even more rich and versatile kotlin scripting interpreter.

https://holgerbrandl.github.io/kscript_kotlinconf_2017/kscript_kotlinconf.html[kscript presentation from KotlinConf2017!]

'''

• <<Installation>>
• <<Script Input Modes>>
• <<Script Configuration>>
• <<Text Processing Mode>>
• <<Treat yourself a REPL with --interactive>>
• <<Boostrap IDEA from a scriptlet>>
• <<Deploy scripts as standalone binaries>>
• <<Embed kscript installer within your script>>
• <<kscript configuration file>>
• <<FAQ>>
• <<Support>>
• <<How to contribute?>>
• <<Acknowledgements>>

== Installation

To use kscript just Kotlin is required. To https://kotlinlang.org/docs/tutorials/command-line.html[install Kotlin] we recommend http://sdkman.io/install[sdkman]:

[source,bash]

curl -s "https://get.sdkman.io" | bash # install sdkman source "$HOME/.sdkman/bin/sdkman-init.sh" # add sdkman to PATH

sdk install kotlin # install Kotlin

Once Kotlin is ready, you can install kscript with

[source,bash]

sdk install kscript

To test your installation simply run

[source,bash]

kscript --help

This will check and inform about updates. To update kscript simply install it again as described above.

=== Run with docker

We provide an executable docker container to run kscript

[source,bash]

using the latest version of kscript

docker run -i kscripting/kscript 'println("Hello, world!")'

or using versioned container

docker run -i kscripting/kscript:4.2.0 'println("Hello, world!")'

To use a script file outside the container as input, you could do

[source,bash]

docker run -i kscripting/kscript - < script.kts

This will make kscript read the code from stdin while piping the file. Beware that the -i flag is needed to have stdout redirected outside the container.

Please note, that currently @Import are not supported when using a dockerized kscript. Also, any resource outside the container context may not be resolved correctly. To overcome this limitation, you could use for instance https://docs.docker.com/storage/bind-mounts/[bind mounts].

=== Installation without sdkman

If you have Kotlin already, and you would like to install the latest kscript release without using sdkman you can do so by unzipping the https://github.com/kscripting/kscript/releases/latest[latest ] binary release. Don't forget to update your $PATH accordingly.

=== Installation with Homebrew

On MacOS you can install kscript also with https://brew.sh/[Homebrew]

[source,bash]

brew install kscripting/tap/kscript

To upgrade to latest version

[source,bash]

brew update brew upgrade kscripting/tap/kscript

=== Installation on Arch Linux

On Arch Linux, kscript is available through the https://aur.archlinux.org/packages/kscript/[Arch Linux User repository (AUR)]. Use your favorite https://wiki.archlinux.org/index.php/AUR_helpers[AUR helper] to install, e.g. yay:

[source,bash]

yay -S kscript

There is an uncommon directory layout of Kotlin package for Arch Linux, which causes problems when using kscript with default Kotlin package. Two workarounds for ArchLinux exists, which can be used to make 'kscript' working with ArchLinux:

. Manually create symlinks in the system… + [source,bash]

sudo mkdir /usr/share/kotlin/bin sudo ln -s /usr/bin/kotlin /usr/share/kotlin/bin/kotlin
sudo ln -s /usr/bin/kotlinc /usr/share/kotlin/bin/kotlinc

. …or install Kotlin using SdkMan: + <<Installation,Installation using SdkMan>>

The problem should be fixed in the Kotlin package for ArchLinux. See more in the Github issue: + https://github.com/kscripting/kscript/issues/371

=== Installation on Windows

On Windows, kscript is available through the https://github.com/ScoopInstaller/Extras/blob/master/bucket/kscript.json[Scoop Extras bucket]. Use the following commands to install:

[source,powershell]

scoop bucket add extras scoop install kscript

To install scoop use the https://github.com/ScoopInstaller/Install[official guide].

=== Build it yourself

To build kscript yourself, simply clone the repo and do

[source,bash]

./gradlew assemble

Run kscript from output dir

./build/kscript/bin/kscript

== Script Input Modes

The main mode of operation is kscript <script>.

The <script> can be a Kotlin *.kts script file , a script URL, - for stdin, a process substitution file handle, a *.kt source file with a main method, or some kotlin code.

=== Interpreter Usage

To use kscript as interpreter for a script just point to it in the shebang line of your Kotlin scripts:

[source,kotlin]

#!/usr/bin/env kscript

println("Hello from Kotlin!") for (arg in args) { println("arg: $arg") }

=== Inlined Usage

To use kscript in a workflow without creating an additional script file, you can also use one of its supported modes for inlined usage. The following modes are supported:

• Directly provide a Kotlin scriptlet as argument

[source,bash]

kscript 'println("hello world")'

• Pipe a Kotlin snippet into kscript and instruct it to read from stdin by using - as script argument

[source,bash]

echo 'println("Hello Kotlin.")' | kscript -

• Using heredoc (preferred solution for inlining) which gives you some more flexibility to also use single quotes in your script:

[source,bash]

kscript - <<"EOF" println("It's a beautiful day!") EOF

• Since the piped content is considered as a regular script it can also have dependencies

[source,bash]

kscript - <<"EOF" @file:DependsOn("com.offbytwo:docopt:0.6.0.20150202", "log4j:log4j:1.2.14")

import org.docopt.Docopt val docopt = Docopt("Usage: jl <command> [options] [<joblist_file>]")

println("hello again") EOF

• Finally, (for sake of completeness), it also works with process substitution and for sure you can always provide additional arguments (exposed as args : Array<String> within the script)

[source,bash]

kscript <(echo 'println("k-onliner")') arg1 arg2 arg3

Inlined kscripts are also cached based on md5 checksum, so running the same snippet again will use a cached jar ( sitting in ~/.kscript).

=== URL usage

To support remote scriplet repositories, kscript can also work with URLs. Consider the following https://github.com/kscripting/kscript/blob/master/examples/url_example.kts[hello-world-gist-scriptlet] which is hosted on github (but any URL would work). To run it locally as a tool simply refer to it (here using the shortened https://raw.githubusercontent.com/kscripting/kscript/master/examples/url_example.kts[raw-URL] of the script for better readability)

[source,bash]

kscript https://git.io/v1cG6 my argu ments

To streamline the usage, the first part could be even aliased:

[source,bash]

alias hello_kscript="kscript https://git.io/v1cG6" hello_kscript my argu ments

Via this mechanism, kscript allows for easy integration of remotely hosted (mini) programs into data workflows.

URL-scripts are cached locally to speed up processing, and kscript --clear-cache can be used to wipe the cache if needed.

See this http://holgerbrandl.github.io/kotlin/2016/12/02/mini_programs_with_kotlin.html[blogpost] for a more extensive overview about URL support in kscript.

== Script Configuration

The following directives supported by kscript to configure scripts:

• @file:DependsOn to declare dependencies with gradle-style locators
• @file:Import to source kotlin files into the script
• @file:EntryPoint to declare the application entrypoint for kotlin *.kt applications
• @file:CompilerOptions to configure the compilation options
• @file:KotlinOptions to configure the kotlin/java runtime environment

=== Declare dependencies with @file:DependsOn

To specify dependencies simply use gradle-style locators. Here's an example using https://github.com/docopt/docopt.java[docopt] and http://logging.apache.org/log4j/2.x/[log4j]

[source,kotlin]

#!/usr/bin/env kscript @file:DependsOn("com.offbytwo:docopt:0.6.0.20150202", "log4j:log4j:1.2.14")

import org.d