Git Product home page Git Product logo

ktsh's Introduction

KtSh

An open source library to execute shell commands on Android or the JVM, written in Kotlin.

License Build Status Maven Central

Downloads

Download the latest JAR or grab via Gradle:

implementation 'com.jaredrummler:ktsh:1.0.0'

Alternatively, you can simply copy Shell.kt file to your project.

Usage

Basic usage:

val shell = Shell("sh")                         // create a shell
val result = shell.run("echo 'Hello, World!'")  // execute a command
if (result.isSuccess) {                         // check if the exit-code was 0
    println(result.stdout())                    // prints "Hello, World!"
}

Construct a new Shell instance:

// Construct a new shell instance with additional environment variables
val shell = Shell("sh", "USER" to "Chuck Norris", "ENV_VAR" to "VALUE")

// Construct a new shell instance with path to the shell:
val bash = Shell("/bin/bash")

Note: If the shell does not exist a Shell.NotFoundException is thrown as a RuntimeException.

Execute a command and get the result:

val shell = Shell.SH
val result: Shell.Command.Result = shell.run("ls")

A Shell.Command.Result contains the following:

  • stdout: A list of lines read from the standard input stream.
  • stderr: A list of lines read from the standard error stream.
  • exitCode: The exit status from running the command.
  • details: Additional information (start, stop, elapsed time, id, command)

Add a callback when stdout or stderr is read:

shell.addOnStderrLineListener(object : Shell.OnLineListener {
  override fun onLine(line: String) {
      // do something
  }
})

Add a callback that is invoked each time a command completes:

shell.addOnCommandResultListener(object : Shell.OnCommandResultListener {
  override fun onResult(result: Shell.Command.Result) {
    // do something with the result
  }
})

Execute a command with custom options:

Optionally, you can configure how each command executes by setting a timeout, redirecting stderr to stdout, add callbacks for when the command reads a line from stdout/stderr or is cancelled.

// NOTE: all of these are optional
val result = Shell.SH.run(command) {
  // Kill the command after 1 minute
  timeout = Shell.Timeout(1, TimeUnit.MINUTES)
  // Redirect STDOUT to STDERR
  redirectErrorStream = false
  // Callbacks:
  onCancelled = {
    // The command was cancelled
  }
  onStdErr = { line: String ->
    // Do something when reading a line from standard error stream
  }
  onStdOut = { line: String ->
    // Do something when reading a line from standard output stream
  }
  // Do not notify any listeners added via Shell.addOnStderrLineListener and Shell.addOnStdoutLineListener
  notify = false
}

Check the state of the shell:

if (shell.isRunning()) {
  // The shell is running a command
} else if (shell.isShutdown()) {
  // The shell has been killed
} else if (shell.isIdle()) {
  // The shell is open and not running any commands
}

or

when (shell.state) {
  State.Idle -> TODO()
  State.Running -> TODO()
  State.Shutdown -> TODO()
}

Shutdown the shell

shell.shutdown()

Interrupt waiting for a command to complete:

shell.interrupt()

Background processing on Android

Creating a new instance of a Shell or executing commands should be done on a separate thread other than the UI thread. This is up to the library user. An example of this can be found in the demo project using Kotlin coroutines and AndroidX libraries:

fun run(
    shell: Shell,
    command: String,
    callback: (result: Shell.Command.Result) -> Unit
) = viewModelScope.launch {
    val result = withContext(Dispatchers.IO) { shell.run(command) }
    withContext(Dispatchers.Main) { callback(result) }
}

Structure

  • buildSrc - contains dependencies, plugins, versions for Gradle build logic
  • build.gradle.kts - root gradle config file
  • settings.gradle.kts - root gradle settings file
  • library - the ktsh library
  • library/src/test - unit tests for the library
  • demo - Android demo project using ktsh
  • scripts - scripts to publish library to maven central
  • .github - any files for the github page

Similar projects:

License

Copyright (C) 2021 Jared Rummler

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

ktsh's People

Contributors

jaredrummler avatar

Watchers

James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.