{"id":24143637,"url":"https://github.com/pgreze/kotlin-process","last_synced_at":"2025-04-06T16:11:36.998Z","repository":{"id":40738631,"uuid":"336182881","full_name":"pgreze/kotlin-process","owner":"pgreze","description":"Kotlin Coroutines friendly way to run an external process","archived":false,"fork":false,"pushed_at":"2025-01-27T09:46:39.000Z","size":222,"stargazers_count":99,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T14:11:11.181Z","etag":null,"topics":["kotlin","kotlin-script","kotlin-scripting","process"],"latest_commit_sha":null,"homepage":"https://kotlin-process.netlify.app/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgreze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-02-05T06:18:41.000Z","updated_at":"2025-03-29T00:21:33.000Z","dependencies_parsed_at":"2025-01-12T05:28:19.337Z","dependency_job_id":"997e0178-34f4-48fe-860c-49aba0a62d54","html_url":"https://github.com/pgreze/kotlin-process","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgreze%2Fkotlin-process","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgreze%2Fkotlin-process/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgreze%2Fkotlin-process/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgreze%2Fkotlin-process/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgreze","download_url":"https://codeload.github.com/pgreze/kotlin-process/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509222,"owners_count":20950232,"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":["kotlin","kotlin-script","kotlin-scripting","process"],"created_at":"2025-01-12T05:28:11.005Z","updated_at":"2025-04-06T16:11:36.981Z","avatar_url":"https://github.com/pgreze.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kotlin-process [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![Build](https://github.com/pgreze/kotlin-process/workflows/Build/badge.svg) [![codecov](https://codecov.io/gh/pgreze/kotlin-process/branch/main/graph/badge.svg?token=PDyl2T0EEB)](https://codecov.io/gh/pgreze/kotlin-process)\n\nFunctional Kotlin friendly way to create external system processes by leveraging:\n- Kotlin coroutines\n- the powerful but convoluted [ProcessBuilder](https://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html)\n\n## Installation  [![central](https://maven-badges.herokuapp.com/maven-central/com.github.pgreze/kotlin-process/badge.svg?style={style})](https://search.maven.org/artifact/com.github.pgreze/kotlin-process) [![](https://img.shields.io/badge/Java-8-blue)](https://adoptopenjdk.net/) [![](https://img.shields.io/badge/Kotlin-2.1.10-blue)](https://kotlinlang.org/)\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    // Check the 🔝 maven central badge 🔝 for the latest $kotlinProcessVersion\n    implementation(\"com.github.pgreze:kotlin-process:$kotlinProcessVersion\")\n}\n```\n\nOr in your kotlin script:\n\n```kotlin\n@file:DependsOn(\"org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1\")\n@file:DependsOn(\"com.github.pgreze:kotlin-process:$kotlinProcessVersion\")\n```\n\n## Usage [![](https://img.shields.io/badge/dokka-read-blue)](https://kotlin-process.netlify.app/)\n\n### Launch a script and consume its results\n\nStarts a program and prints its stdout/stderr outputs to the terminal:\n\n```kotlin\nimport com.github.pgreze.process.process\nimport kotlinx.coroutines.runBlocking\n\nrunBlocking {\n    val res = process(\"echo\", \"hello world\")\n\n    check(res.resultCode == 0)\n\n    // By default process output is displayed in the console.\n    check(res.output == emptyList\u003cString\u003e())\n}\n```\n\nThe next step would probably be to capture the output stream,\nin order to process some data from our own-made script:\n\n```kotlin\nval output = process(\n    \"./my-script.sh\", arg1, arg2,\n\n    // Capture stdout lines to do some operations after\n    stdout = Redirect.CAPTURE,\n\n    // Default value: prints to System.err\n    stderr = Redirect.PRINT,\n\n).unwrap() // Fails if the resultCode != 0\n\n// TODO: process the output\nprintln(\"Success:\\n${output.joinToString(\"\\n\")}\")\n```\n\nNotice that if you want to capture both stdout and stderr,\nthere will be no way to differentiate them in the returned output:\n\n```kotlin\nval res = process(\n    \"./long-and-dangerous.sh\", arg1, arg2,\n\n    // Both streams will be captured,\n    // preserving their orders but mixing them in the given output.\n    stdout = Redirect.CAPTURE,\n    stderr = Redirect.CAPTURE,\n\n    // Allows to consume line by line without delay the provided output.\n    consumer = { line -\u003e TODO(\"process $line\") },\n)\n\nprintln(\"Script finished with result=${res.resultCode}\")\nprintln(\"stdout+stderr:\\n\" + res.output.joinToString(\"\\n\"))\n```\n\nIt's also possible to redirect an output stream to a file,\nor manually by consuming a Flow\u003cString\u003e instance.\n\n```kotlin\nimport com.github.pgreze.process.Redirect\nimport com.github.pgreze.process.process\nimport java.io.File\nimport java.util.Collections\nimport kotlinx.coroutines.flow.toList\nimport kotlinx.coroutines.runBlocking\n\nval errLines = Collections.synchronizedList(mutableListOf\u003cString\u003e())\nval res = process(\n    \"./my-script.sh\", arg1, arg2,\n\n    // You can save the execution result in a file,\n    stdout = Redirect.ToFile(File(\"my-input.txt\")),\n\n    // If you want to handle this stream yourself,\n    // a Flow\u003cString\u003e instance can be used.\n    stderr = Redirect.Consume { flow -\u003e flow.toList(errLines) },\n)\n```\n\nThe last but not least, you can just silence a stream with Redirect.SILENT 😶\n\n### Control the environment\n\nSeveral other options are available to control the script environment:\n\n```kotlin\nimport com.github.pgreze.process.InputSource\nimport java.io.File\n\nval res = process(\n    \"./my-script.sh\",\n    \n    // Provides the input as a string, similar to:\n    // $ echo \"hello world\" | my-script.sh\n    stdin = InputSource.fromString(\"hello world\"),\n\n    // Inject custom environment variables:\n    env = mapOf(\"MY_ENV_VARIABLE\" to \"42\"),\n\n    // Override the working directory:\n    directory = File(\"./a/directory\"),\n)\n```\n\nThere are other ways to provide the process input:\n\n```kotlin\n// From a file:\nprocess(\n    \"./my-script.sh\",\n    stdin = InputSource.FromFile(File(\"my-input.txt\")),\n)\n\n// From an InputStream:\nprocess(\n    \"./my-script.sh\",\n    stdin = InputSource.fromInputStream(myInputStream)),\n)\n\n// Manually by using the raw OutputStream:\nprocess(\n    \"./my-script.sh\",\n    stdin = InputSource.FromStream { out: OutputStream -\u003e\n        out.write(\"hello world\\n\".toByteArray())\n        out.flush()\n    },\n)\n```\n\n## Alternative(s)\n\n1. https://github.com/jakubriegel/kotlin-shell\n2. https://github.com/lordcodes/turtle\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgreze%2Fkotlin-process","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgreze%2Fkotlin-process","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgreze%2Fkotlin-process/lists"}