{"id":13428191,"url":"https://github.com/kscripting/kscript","last_synced_at":"2025-05-15T05:08:05.585Z","repository":{"id":37390601,"uuid":"53889290","full_name":"kscripting/kscript","owner":"kscripting","description":"Scripting enhancements for Kotlin","archived":false,"fork":false,"pushed_at":"2024-06-12T19:29:45.000Z","size":1792,"stargazers_count":2104,"open_issues_count":40,"forks_count":124,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-11T15:57:07.995Z","etag":null,"topics":["bash","dependency-resolution","kotlin","mpi-cbg","scripting"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kscripting.png","metadata":{"files":{"readme":"README.adoc","changelog":"NEWS.adoc","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-14T20:23:27.000Z","updated_at":"2025-04-06T16:20:46.000Z","dependencies_parsed_at":"2024-01-14T02:37:13.613Z","dependency_job_id":"fb28750e-a296-4437-8092-a1f2bf5276f9","html_url":"https://github.com/kscripting/kscript","commit_stats":null,"previous_names":["holgerbrandl/kscript"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kscripting%2Fkscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kscripting%2Fkscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kscripting%2Fkscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kscripting%2Fkscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kscripting","download_url":"https://codeload.github.com/kscripting/kscript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","dependency-resolution","kotlin","mpi-cbg","scripting"],"created_at":"2024-07-31T01:00:48.883Z","updated_at":"2025-05-15T05:08:00.576Z","avatar_url":"https://github.com/kscripting.png","language":"Kotlin","readme":"= kscript - Having fun with Kotlin scripting\n\nimage:https://img.shields.io/github/release/kscripting/kscript.svg[GitHub release,link=https://github.com/kscripting/kscript/releases]\nimage:https://github.com/kscripting/kscript/actions/workflows/build.yml/badge.svg[Build Status,link=https://github.com/kscripting/kscript/actions/workflows/build.yml]\nimage:https://badges.gitter.im/kscripting/kscript.svg[Gitter,link=https://gitter.im/kscripting/kscript?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge]\n\nEnhanced scripting support for https://kotlinlang.org/[Kotlin] on *nix-based and Windows systems.\n\nKotlin has some built-in support for scripting already, but it is not yet feature-rich enough to be a viable alternative in the shell.\n\nIn particular this wrapper around `kotlinc` adds\n\n* Compiled script caching (using md5 checksums)\n* Dependency declarations using gradle-style resource locators and automatic dependency resolution\n* More options to provide scripts including interpreter mode, reading from stdin, local files or URLs\n* Embedded configuration for Kotlin runtime options\n* Support library to ease the writing of Kotlin scriptlets\n* Deploy scripts as stand-alone binaries\n\nTaken all these features together, `kscript` provides an easy-to-use, very flexible, and almost zero-overhead solution\nto write self-contained mini-applications with Kotlin.\n\n*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.\n\n*https://holgerbrandl.github.io/kscript_kotlinconf_2017/kscript_kotlinconf.html[`kscript` presentation from KotlinConf2017!]*\n\n'''\n* \u003c\u003cInstallation\u003e\u003e\n* \u003c\u003cScript Input Modes\u003e\u003e\n* \u003c\u003cScript Configuration\u003e\u003e\n* \u003c\u003cText Processing Mode\u003e\u003e\n* \u003c\u003cTreat yourself a REPL with `--interactive`\u003e\u003e\n* \u003c\u003cBoostrap IDEA from a scriptlet\u003e\u003e\n* \u003c\u003cDeploy scripts as standalone binaries\u003e\u003e\n* \u003c\u003cEmbed kscript installer within your script\u003e\u003e\n* \u003c\u003ckscript configuration file\u003e\u003e\n* \u003c\u003cFAQ\u003e\u003e\n* \u003c\u003cSupport\u003e\u003e\n* \u003c\u003cHow to contribute?\u003e\u003e\n* \u003c\u003cAcknowledgements\u003e\u003e\n\n== Installation\n\nTo use `kscript` just Kotlin is required.\nTo https://kotlinlang.org/docs/tutorials/command-line.html[install Kotlin] we\nrecommend http://sdkman.io/install[sdkman]:\n\n[source,bash]\n----\ncurl -s \"https://get.sdkman.io\" | bash     # install sdkman\nsource \"$HOME/.sdkman/bin/sdkman-init.sh\"  # add sdkman to PATH\n\nsdk install kotlin                         # install Kotlin\n----\n\nOnce Kotlin is ready, you can install `kscript` with\n\n[source,bash]\n----\nsdk install kscript\n----\n\nTo test your installation simply run\n\n[source,bash]\n----\nkscript --help\n----\n\nThis will check and inform about updates. To update `kscript` simply install it again as described above.\n\n=== Run with docker\n\nWe provide an executable docker container to run `kscript`\n\n[source,bash]\n----\n# using the latest version of kscript\ndocker run -i kscripting/kscript 'println(\"Hello, world!\")'\n\n# or using versioned container\ndocker run -i kscripting/kscript:4.2.0 'println(\"Hello, world!\")'\n----\n\nTo use a script file outside the container as input, you could do\n\n[source,bash]\n----\ndocker run -i kscripting/kscript - \u003c script.kts\n----\n\nThis will make `kscript` read the code from stdin while piping the file. Beware that the -i flag is needed to have\nstdout redirected outside the container.\n\nPlease note, that currently `@Import` are not supported when using a dockerized kscript. Also, any resource outside the\ncontainer context may not be resolved correctly. To overcome this limitation, you could use for\ninstance https://docs.docker.com/storage/bind-mounts/[bind mounts].\n\n=== Installation without `sdkman`\n\nIf you have Kotlin already, and you would like to install the latest `kscript` release without using `sdkman`\nyou can do so by unzipping the https://github.com/kscripting/kscript/releases/latest[latest ] binary release. Don't\nforget to update your `$PATH` accordingly.\n\n=== Installation with Homebrew\n\nOn MacOS you can install `kscript` also with https://brew.sh/[Homebrew]\n\n[source,bash]\n----\nbrew install kscripting/tap/kscript\n----\n\nTo upgrade to latest version\n\n[source,bash]\n----\nbrew update\nbrew upgrade kscripting/tap/kscript\n----\n\n=== Installation on Arch Linux\n\nOn Arch Linux, `kscript` is available through\nthe https://aur.archlinux.org/packages/kscript/[Arch Linux User repository (AUR)]. Use your\nfavorite https://wiki.archlinux.org/index.php/AUR_helpers[AUR helper] to install, e.g. `yay`:\n\n[source,bash]\n----\nyay -S kscript\n----\n\nThere is an uncommon directory layout of Kotlin package for Arch Linux, which causes problems when using kscript with\ndefault Kotlin package.\nTwo workarounds for ArchLinux exists, which can be used to make 'kscript' working with ArchLinux:\n\n. Manually create symlinks in the system…\n+\n[source,bash]\n----\nsudo mkdir /usr/share/kotlin/bin\nsudo ln -s /usr/bin/kotlin /usr/share/kotlin/bin/kotlin   \nsudo ln -s /usr/bin/kotlinc /usr/share/kotlin/bin/kotlinc\n----\n\n. …or install Kotlin using SdkMan:\n+\n\u003c\u003cInstallation,Installation using SdkMan\u003e\u003e\n\nThe problem should be fixed in the Kotlin package for ArchLinux. See more in the Github issue: +\nhttps://github.com/kscripting/kscript/issues/371\n\n=== Installation on Windows\n\nOn Windows, `kscript` is available through\nthe https://github.com/ScoopInstaller/Extras/blob/master/bucket/kscript.json[Scoop Extras bucket]. Use the following commands to install:\n\n[source,powershell]\n----\nscoop bucket add extras\nscoop install kscript\n----\n\nTo install `scoop` use the https://github.com/ScoopInstaller/Install[official guide].\n\n=== Build it yourself\n\nTo build `kscript` yourself, simply clone the repo and do\n\n[source,bash]\n----\n./gradlew assemble\n\n## Run kscript from output dir\n./build/kscript/bin/kscript\n----\n\n== Script Input Modes\n\nThe main mode of operation is `kscript \u003cscript\u003e`.\n\nThe `\u003cscript\u003e` can be a Kotlin `*.kts` script file , a script URL, `-` for stdin, a process substitution file handle,\na `*.kt` source file with a main method, or some kotlin code.\n\n=== Interpreter Usage\n\nTo use `kscript` as interpreter for a script just point to it in the shebang line of your Kotlin scripts:\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n\nprintln(\"Hello from Kotlin!\")\nfor (arg in args) {\n    println(\"arg: $arg\")\n}\n----\n\n=== Inlined Usage\n\nTo use `kscript` in a workflow without creating an additional script file, you can also use one of its supported modes\nfor _inlined usage_. The following modes are supported:\n\n* Directly provide a Kotlin scriptlet as argument\n\n[source,bash]\n----\nkscript 'println(\"hello world\")'\n----\n\n* Pipe a Kotlin snippet into `kscript` and instruct it to read from `stdin` by using `-` as script argument\n\n[source,bash]\n----\necho 'println(\"Hello Kotlin.\")' |  kscript -\n----\n\n* Using `heredoc` (preferred solution for inlining) which gives you some more flexibility to also use single quotes in your script:\n\n[source,bash]\n----\nkscript - \u003c\u003c\"EOF\"\nprintln(\"It's a beautiful day!\")\nEOF\n----\n\n* Since the piped content is considered as a regular script it can also have dependencies\n\n[source,bash]\n----\nkscript - \u003c\u003c\"EOF\"\n@file:DependsOn(\"com.offbytwo:docopt:0.6.0.20150202\", \"log4j:log4j:1.2.14\")\n\nimport org.docopt.Docopt\nval docopt = Docopt(\"Usage: jl \u003ccommand\u003e [options] [\u003cjoblist_file\u003e]\")\n\nprintln(\"hello again\")\nEOF\n----\n\n* Finally, (for sake of completeness), it also works with process substitution and for sure you can always provide\n additional arguments (exposed as `args : Array\u003cString\u003e` within the script)\n\n[source,bash]\n----\nkscript \u003c(echo 'println(\"k-onliner\")') arg1 arg2 arg3 \n----\n\nInlined _kscripts_ are also cached based on `md5` checksum, so running the same snippet again will use a cached jar (\nsitting in `~/.kscript`).\n\n=== URL usage\n\nTo support remote scriplet repositories, `kscript` can also work with URLs. Consider the\nfollowing https://github.com/kscripting/kscript/blob/master/examples/url_example.kts[hello-world-gist-scriptlet]\nwhich is hosted on github (but any URL would work). To run it locally as a tool simply refer to it (here using the\nshortened https://raw.githubusercontent.com/kscripting/kscript/master/examples/url_example.kts[raw-URL] of the\nscript for better readability)\n\n[source,bash]\n----\nkscript https://git.io/v1cG6 my argu ments \n----\n\nTo streamline the usage, the first part could be even aliased:\n\n[source,bash]\n----\nalias hello_kscript=\"kscript https://git.io/v1cG6\"\nhello_kscript my argu ments\n----\n\nVia this mechanism, `kscript` allows for easy integration of remotely hosted (mini) programs into data workflows.\n\nURL-scripts are cached locally to speed up processing, and `kscript --clear-cache` can be used to wipe the cache if\nneeded.\n\nSee this http://holgerbrandl.github.io/kotlin/2016/12/02/mini_programs_with_kotlin.html[blogpost] for a more extensive\noverview about URL support in `kscript`.\n\n== Script Configuration\n\nThe following directives supported by `kscript` to configure scripts:\n\n* `@file:DependsOn` to declare dependencies with gradle-style locators\n* `@file:Import` to source kotlin files into the script\n* `@file:EntryPoint` to declare the application entrypoint for kotlin `*.kt` applications\n* `@file:CompilerOptions` to configure the compilation options\n* `@file:KotlinOptions` to configure the kotlin/java runtime environment\n\n=== Declare dependencies with `@file:DependsOn`\n\nTo specify dependencies simply use gradle-style locators. Here's an example\nusing https://github.com/docopt/docopt.java[docopt] and http://logging.apache.org/log4j/2.x/[log4j]\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n@file:DependsOn(\"com.offbytwo:docopt:0.6.0.20150202\", \"log4j:log4j:1.2.14\")\n\nimport org.docopt.Docopt\nimport java.util.*\n\nval usage = \"\"\"\nUse this cool tool to do cool stuff\nUsage: cooltool.kts [options] \u003cigenome\u003e \u003cfastq_files\u003e...\n\nOptions:\n --gtf \u003cgtfFile\u003e     Custom gtf file instead of igenome bundled copy\n --pc-only           Use protein coding genes only for mapping and quantification\n\"\"\"\n\nval doArgs = Docopt(usage).parse(args.toList())\n\nprintln(\"Hello from Kotlin!\")\nprintln(\"Parsed script arguments are: \\n$doArgs\")\n----\n\n`kscript` will read dependencies from all lines in a script that start with `@file:DependsOn` (if any). Multiple\ndependencies can\nbe split by comma, space or semicolon.\n\n=== Configure the runtime with `@file:KotlinOptions`\n\n`kscript` allows to provide a `@file:KotlinOptions` directive followed by parameters passed on to `kotlin` similar to\nhow\ndependencies are defined:\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n@file:KotlinOptions(\"-J-Xmx5g\", \"-J-server\")\n\nprintln(\"Hello from Kotlin with 5g of heap memory running in server mode!\")\n----\n\nNote: Similar to the runtime you can also tweak the compile step by providing `@file:CompilerOptions`.\n\n=== Ease prototyping with `@file:Import`\n\n`kscript` supports an `@file:Import` directive to directly include other source files without prior compilation.\nAbsolute\nand relative paths, as well as URLs are supported. Example:\n\n[source,kotlin]\n----\n//utils.kt\nfun Array\u003cDouble\u003e.median(): Double {\n    val (lower, upper) = sorted().let { take(size / 2) to takeLast(size / 2) }\n    return if (size % 2 == 0) (lower.last() + upper.first()) / 2.0 else upper.first()\n}\n----\n\nWhich can be now used using the `@file:Import` directive with\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n\n@file:Import(\"utils.kt\")\n\nval robustMean = listOf(1.3, 42.3, 7.0).median()\nprintln(robustMean)\n----\n\nThe argument can be an URL, absolute or relative file path. Note that URLs used in include directives are cached locally\nto speed up processing, that is `kscript` won't fetch URLs again unless the user actively clears the cache\nwith `kscript --clear-cache`.\n\nFor more examples see link:test/resources/includes/include_variations.kts[here].\n\n=== Use `@file:EntryPoint` to run applications with `main` method\n\n`kscript` also supports running regular Kotlin `kt` files.\n\nExample: `./examples/Foo.kt`:\n\n[source,kotlin]\n----\npackage examples\n\n@file:EntryPoint(\"examples.Bar\")\n\nclass Bar {\n    companion object {\n        @JvmStatic\n        fun main(args: Array\u003cString\u003e) {\n            println(\"Foo was called\")\n        }\n    }\n}\n\nfun main(args: Array\u003cString\u003e) = println(\"main was called\")\n----\n\nTo run top-level main instead we would use `@file:EntryPoint(\u0026quot;examples.FooKt\u0026quot;)`\n\nThe latter is the default for `kt` files and could be omitted\n\n=== Examples of annotation driven configuration\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n\n// Declare dependencies\n@file:DependsOn(\"com.github.holgerbrandl:kutils:0.12\")\n@file:DependsOn(\"com.beust:klaxon:0.24\", \"com.github.kittinunf.fuel:fuel:2.3.1\")\n\n// To use a custom maven repository you can declare it with\n@file:Repository(\"http://maven.imagej.net/content/repositories/releases\")\n\n// For compatibility with https://github.com/ligee/kotlin-jupyter kscript supports also\n@file:DependsOnMaven(\"net.clearvolume:cleargl:2.0.1\")\n// Note that for compatibility reasons, only one locator argument is allowed for @DependsOnMaven\n\n// also protected artifact repositories are supported, see \u003chttps://github.com/kscripting/kscript/blob/master/test/TestsReadme.md#manual-testing\u003e\n// @file:Repository(\"my-art\", \"http://localhost:8081/artifactory/authenticated_repo\", user=\"auth_user\", password=\"password\")\n// You can use environment variables for user and password when string surrounded by double {} brackets \n// @file:Repository(\"my-art\", \"http://localhost:8081/artifactory/authenticated_repo\", user=\"{{ARTIFACTORY_USER}}\", password=\"{{ARTIFACTORY_PASSWORD}}\")\n// will be use 'ARTIFACTORY_USER' and 'ARTIFACTORY_PASSWORD' environment variables\n// if the value doesn't found in the script environment  will fail\n\n// Include helper scripts without deployment or prior compilation\n@file:Import(\"util.kt\")\n\n// Define kotlin options\n@file:KotlinOptions(\"-J-Xmx5g\")\n@file:KotlinOptions(\"-J-server\")\n@file:CompilerOptions(\"-jvm-target 1.8\")\n\n// declare application entry point (applies on for kt-files)\n@file:EntryPoint(\"Foo.bar\")\n\nprint(\"1+1\")\n----\n\nTo enable the use of these annotations in Intellij, the user must add the following artifact to the project\ndependencies:\n\n----\nio.github.kscripting:kscript-annotations:1.5\n----\n\n`kscript` will automatically detect an annotation-driven script, and if so will declare a dependency on this artifact\ninternally.\n\nNote, that if a script is located in a package other than the root package, you need to import the annotations with (\ne.g. `import DependsOn`).\n\n== Text Processing Mode\n\n`kscript` can be used as a speedier and more flexible substitute for built-in terminal text tools such as `awk` or `sed`\n. Its text processing mode can be enabled with `-t` or `--text`. If so, `kscript` will\n\n* Declare `com.github.kscripting:kscript-support-api:1.2.5` as dependency for the script.\n This https://github.com/kscripting/kscript-support-api[support library] eases the writing of Kotlin scriptlets for\n text-processing. It includes solutions to common use-cases like argument parsing, data streaming, IO utilities, and\n various iterators to streamline the writing of scriptlets for text processing.\n* Import the `kscript.*` namespace\n* Define variable `val lines = kscript.text.resolveArgFile(args)` which returns an iterator over the lines in the first\n input argument of the script, or the standard input if no file arguments are provided to the script\n\nThis allows to replace `awk`ward constructs (or `sed` or`perl`) with _kotlinesque_ solutions such as\n\n[source,bash]\n----\ncat some_file | kscript -t 'lines\n    .filter { \"^de0[-0]*\".toRegex().matches(it) }\n    .map { it + \"foo:\" }\n    .print()\n'\n----\n\nIn this example, the extension\nmethod https://github.com/kscripting/kscript-support-api/blob/master/src/main/kotlin/kscript/text/StreamUtil.kt#L34[`Iterable\u003cString\u003e.print()`]\nto print the lines to stdout comes from the support API. The rest is stdlib Kotlin.\n\nFor more examples using the support library see\nthis http://holgerbrandl.github.io/kotlin/2017/05/08/kscript_as_awk_substitute.html[blog post].\n\n== Treat yourself a REPL with `--interactive`\n\nTo create an interactive kotlin shell (\naka https://kotlinlang.org/docs/tutorials/command-line.html#running-the-repl[REPL]) with all script dependencies added\nto the classpath you can use `--interactive`.\n\nFor example, let's assume the following short script, named `CountRecords.kts`\n\n[source,kotlin]\n----\n#!/usr/bin/env kscript\n@file:DependsOn(\"com.github.holgerbrandl:kutils:0.12\")\n\nimport de.mpicbg.scicomp.bioinfo.openFasta\n\nif (args.size != 1) {\n    System.err.println(\"Usage: CountRecords \u003cfasta\u003e\")\n    kotlin.system.exitProcess(-1)\n}\n\nval records = openFasta(java.io.File(args[0]))\nprintln(records.count())\n----\n\nTo build a REPL that has the declared artifact in its classpath, we can just do\n\n[source,bash]\n----\nkscript --interactive CountRecords.kts\n----\n\nwhich will bring up the classpath-enhanced REPL:\n\n----\nCreating REPL from CountRecords.kts\nWelcome to Kotlin version 1.1.51 (JRE 1.8.0_151-b12)\n\u003e\u003e\u003e import de.mpicbg.scicomp.bioinfo.openFasta\n\u003e\u003e\u003e \n----\n\n== Boostrap IDEA from a scriptlet\n\nArtifacts and versions will differ between scripts, so it is hard to maintain them all in a single project. To\nnevertheless provide optimal tooling when scripting with Kotlin `kscript` allows to create temporary projects\nfor `\u003cscript\u003e` arguments.\n\n[source,bash]\n----\nkscript --idea CountRecords.kts\n----\n\nIf you have available `gradle` in the path project will be automatically built and if there is `idea` in the path\nthe project will be opened in https://www.jetbrains.com/idea/[IntelliJ IDEA] with a minimalistic project containing\njust your (1) `\u003cscript\u003e` and (2) a generated `build.gradle.kts` file:\n\nimage:misc/readme_images/minus_idea.png[]\n\nThe `idea` command line launcher can can be created in IntelliJ with `Create Command-line Launcher` command, or you can\nset the command used to launch your IntelliJ as `KSCRIPT_COMMAND_IDEA` env property. Similarly, you can set `gradle`\ncommand using `KSCRIPT_COMMAND_GRADLE` env property.\n\n== Deploy scripts as standalone binaries\n\nTo deploy a script simply do\n\n[source,bash]\n----\nkscript --package some_script.kts\n./some_script --arg u ments\n----\n\nThe created binary will contain a compiled copy of the script, as well as all declared dependencies (fatjar). Also\nruntime jvm parameters declared via `@file:KotlinOptions` are used to spin up the JVM.\n\nJust `java` is required to run these binaries.\n\n== Embed kscript installer within your script\n\nTo make a script automatically \u003c\u003cInstallation,install kscript\u003e\u003e and its dependencies on first run if necessary, run:\n\n[source,bash]\n----\nkscript --add-bootstrap-header some_script.kts\n----\n\nNow `some_script.kts` can be shared and run directly on any other machine that has `bash`, without having to go through\nthe \u003c\u003cInstallation\u003e\u003e steps first.\n\nNote that unlike the \u003c\u003cDeploy scripts as standalone binaries,`--package` option\u003e\u003e this doesn't produce a separate file,\nallowing the distributed script to be read and modified(including\nwith \u003c\u003cBoostrap IDEA from a scriptlet,`kscript --idea`\u003e\u003e) similar to what you might expect with bash/python/ruby\nscripts.\nOn the other hand this doesn't embed dependencies within the script(\"fat jar\"), so internet connection may be required\non its first run.\n\n== kscript configuration file\n\nTo keep some options stored permanently in configuration you can create kscript configuration file.\n\nKScript follows XDG directory standard, so the file should be created in (paths are resolved in provided order; first\nexisting path is used):\n\n|===\n|OS |PATH \n\n|*Windows* | %LOCALAPPDATA%\\kscript\\kscript.properties; %USERPROFILE%.config\\kscript\\kscript.properties\n|*MacOs*   | ~/Library/Application Support/kscript/kscript.properties;\n|*Posix*   | \\${XDG_CONFIG_DIR}/kscript/kscript.properties; \\${user.home}/.config/kscript/kscript.properties\n|===\n\nIf the environment variable: *KSCRIPT_DIRECTORY* is defined the configuration file 'kscript.properties' will be placed\ndirectly inside it.\n\nContent of kscript.properties file is a standard Java format, with following properties available:\n\n----\nscripting.preamble=\nscripting.kotlin.opts=\nscripting.repository.url=\nscripting.repository.user=\nscripting.repository.password=\nscripting.directory.artifacts=\n----\n\nExample configuration file:\n\n----\nscripting.preamble=// declare dependencies\\n\\\n@file:DependsOn(\"com.github.holgerbrandl:kutils:0.12\")\\n\\\n\\n\\\n// make sure to also support includes in here\\n\\\n// @file:Import(\"util.kt\")\\n\\\n@file:Import(\"https://raw.githubusercontent.com/kscripting/kscript/master/test/resources/custom_dsl/test_dsl_include.kt\")\\n\\\n\\n\\\n\\n\\\n// define some important variables to be used throughout the dsl\\n\\\nval foo = \"bar\"\n\nscripting.kotlin.opts=-J-Xmx4g\nscripting.repository.url=https://repository.example\nscripting.repository.user=user\nscripting.repository.password=password\n----\n\n== FAQ\n\n=== How to edit kscript in VS Code?\n\nSee https://magnusgunnarsson.se/offentlig/kscript-in-visual-studio-code-vsc/ for a walkthrough and the required editor\nconfiguration.\n\n=== Why is `kscript` not calling the main method in my `.kts` script?\n\nThere is https://kotlinlang.org/docs/tutorials/command-line.html#using-the-command-line-to-run-scripts[no need] for\na `main` method in a Kotlin script. Kotlin `*.kts` scripts can be more simplistic compared to more common kotlin `*.kt`\nsource files. The former work without a `main` method by directly running the provided code from top to bottom. E.g.\n\n----\nprint(\"hello kotlin!\")\n----\n\nis a valid Kotlin `kts` script. Plain and simple, no `main`, no `companion`, just a few bits of code.\n\n=== Does `kscript` also work for regular kotlin `.kt` source files with a `main` as entry point?\n\nYes, (since kscript v1.6) you can run kotlin source files through `kscript`. By default, it will assume a\ntop-level `main` method\nas entry-point.\n\nHowever, in case you're using a companion object to declare the entry point, you need to indicate this via\nthe `@file:Entry`.\n\n=== What are performance and resource usage difference between scripting with kotlin and python?\n\nKotlin is a compiled language, so there is a compilation overhead when you run a script/application written in Kotlin\nfor the first time.\n\nKotlin runs (mainly) on the JVM which needs some time (~200ms) to start up. In contrast, the python interpreter has\nclose to zero warmup time.\n\nI think there is a consensus that JVM programs execute much faster than python equivalents. Still, python might be\nfaster depending on your specific usecase. Also, with kotlin-native becoming more mature, you could compile into native\nbinaries directly, which should bring it close to C/C++ performance.\n\nMain motivations for using Kotlin over Python for scripting and development are\n\n* Kotlin is the better designed, more fluent language with much better tooling around it\n* The JVM dependency ecosystem allows for strict versioning. No more messing around with virtualenv, e.g. to run a short\n 10liner against a specific version of numpy.\n\n=== Does kscript work with java?\n\nThe only language supported by `kscript` is kotlin. For a similar approach centering around Java scripting\nsee https://github.com/maxandersen/jbang[jbang].\n\n=== Can I use custom artifact repositories?\n\nYes, via the `@Repository` annotation. See \u003c\u003cScript Configuration,annotations section\u003e\u003e\nor link:test/resources/custom_mvn_repo_annot.kts[custom_mvn_repo_annot] for a complete example\n\n== Support\n\nFeel welcome to post ideas and suggestions to our https://github.com/kscripting/kscript/issues[tracker].\n\nMore advanced use-cases are documented in the link:docs/user_guide.md[complementary user guide]\n\n== How to contribute?\n\nWe always welcome pull requests and trouble tickets. :-)\n\nHelp to spread the word. Great community articles about `kscript` include\n\n* https://medium.com/@OhadShai/type-safety-in-the-shell-with-kscript-7dd40d022537[Type-safety in the shell with kscript]\n* https://medium.com/@kenkyee/using-kotlin-kscript-for-preprocessing-data-1dbff4eae292[Using Kotlin kscript for Preprocessing Data]\n* https://holgerbrandl.github.io/kotlin/2017/05/08/kscript_as_awk_substitute.html[kscript as substitute for awk]\n* https://hackernoon.com/a-complete-backend-only-with-kotlin-and-your-favourite-text-editor-582b4528688[A complete backend with Kotlin and your favourite text-editor]\n -using kscript\n\nYou could also show your support by upvoting `kscript` here on github, or by voting for issues in Intellij IDEA which\nimpact `kscript`ing. Here are our top 2 tickets/annoyances that we would love to see fixed:\n\n* https://youtrack.jetbrains.com/issue/KT-13347[KT-13347] Good code is red in injected kotlin language snippets\n\nTo allow for more interactive script development, you could also vote/comment on the most annoying REPL issues.\n\n* https://youtrack.jetbrains.net/issue/KT-24789[KT-24789] \"Unresolved reference\" when running a script which is a\n symlink to a script outside of source roots\n* https://youtrack.jetbrains.com/issue/KT-12583[KT-12583] IDE REPL should run in project root directory\n* https://youtrack.jetbrains.com/issue/KT-11409[KT-11409] Allow to \"Send Selection To Kotlin Console\"\n\n== Acknowledgements\n\nThe initial version of `kscript` was kindly contributed by https://github.com/oskargb[Oscar Gonzalez].\n\nSpecial thanks to https://github.com/ilanpillemer[Ilan Pillemer], https://github.com/gildor[Andrey Mischenko ]\n, https://github.com/stephenbyrne-mfj[Stephen Byrne], https://github.com/EugeneSusla[Eugene Susla]\n, https://github.com/elihart[Eli Hart], https://github.com/hj-lee[Hwijae Lee] and https://github.com/oshai[oshai]\nfor https://github.com/kscripting/kscript/graphs/contributors[contributing] PRs to this repo.\n\nThanks also to the https://www.scionics.com/[Scionics Computer Innovation GmbH] and\nthe http://www.mpi-cbg.de[MPI-CBG] for supporting this project.\n\nVersion 3.1 to 4.0 rewrite and current maintenance by https://github.com/aartiPl/[Marcin Kuszczak]\n\n`kscript` was inspired by https://github.com/andrewoma/kotlin-script[kotlin-script] which is another great way (now\ndeprecated) to do scripting in Kotlin.\n","funding_links":[],"categories":["Tools","Kotlin"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkscripting%2Fkscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkscripting%2Fkscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkscripting%2Fkscript/lists"}