KtSh库技术文档

原创于 2024-10-18 12:27:52 发布 · 363 阅读

6 ·

CC 4.0 BY-SA版权

KtSh库技术文档

概览

KtSh是一个开源库，允许开发者在Android设备或JVM上执行Shell命令，采用Kotlin语言编写。本文档旨在提供全面指导，帮助您安装、使用KtSh，并深入了解其API细节。

安装指南

Maven中央仓库

您可以通过Maven将KtSh添加到您的项目中：

<dependency>
  <groupId>com.jaredrummler</groupId>
  <artifactId>ktsh</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

如果您使用的是Gradle，则可以在依赖中添加：

implementation 'com.jaredrummler:ktsh:1.0.0'

此外，可以直接下载最新JAR文件或拷贝Shell.kt源码至您的项目。

项目使用说明

基础使用

创建Shell实例并执行简单的命令：

val shell = Shell("sh")
val result = shell.run("echo '你好，世界！'")
if (result.isSuccess) {
    println(result.stdout())
}

构建Shell实例

您可以自定义环境变量或指定Shell路径：

// 自定义环境变量
val customEnvShell = Shell("sh", "USER" to "超级用户", "CUSTOM_VAR" to "值")

// 指定Shell路径
val bashShell = Shell("/bin/bash")

执行命令与获取结果

val result = Shell.SH.run("ls")

回调监听

KtSh支持对标准错误流、标准输出流的读取事件及命令完成事件设置回调。

shell.addOnStderrLineListener { line ->
    // 处理错误信息
}
shell.addOnCommandResultListener { result ->
    // 处理命令执行结果
}

高级命令执行选项

配置命令执行的超时、重定向错误流、以及回调等：

val result = Shell.SH.run("command") {
    timeout = Shell.Timeout(1, TimeUnit.MINUTES)
    redirectErrorStream = true
    onCancelled = { /* 命令被取消 */ }
    onStdErr = { line -> /* 处理错误输出 */ }
    onStdOut = { line -> /* 处理正常输出 */ }
    notify = false
}

检查Shell状态

检查Shell是否正在运行、已关闭或处于空闲状态：

if (shell.isRunning()) {
    // Shell正执行命令
} else if (shell.isShutdown()) {
    // Shell已关闭
} else if (shell.isIdle()) {
    // Shell空闲
}

关闭与中断

关闭Shell或中断命令执行：

shell.shutdown() // 关闭Shell
shell.interrupt() // 中断命令执行

背景处理与Android注意事项

在Android应用中，务必在非UI线程创建Shell实例或执行命令。示例使用Kotlin协程：

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) }
    }