You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use `kshell` command for running scripts from command line. To read more about it and download the command go [here](https://github.com/jakubriegel/kshell).
99
+
100
+
You can also [download](https://bintray.com/jakubriegel//kotlin-shell/kotlin-shell-kts/_latestVersion) binaries of `kotlin-shell-kts` to use the script definition in custom way.
You can also [download](https://bintray.com/jakubriegel//kotlin-shell/kotlin-shell-core/_latestVersion) binaries of `kotlin-shell-core` to use the library in any other project.
122
+
123
+
## how to run the scripts
124
+
### in Kotlin script
81
125
Kotlin Shell scripts have `sh.kts` extension.
82
126
83
127
Some environment variables may be set to customize script execution. Go to the [environment](#environment) section to learn more.
Calling the `shell` block will provide access to Kotlin Shell API:
156
+
```kotlin
157
+
shell {
158
+
// code
159
+
}
160
+
```
110
161
111
162
## usage
112
163
### writing scripts
164
+
Kotlin Shell is driven by [kotlinx.io](https://github.com/Kotlin/kotlinx-io) and [kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines). Therefore the API is fully non-blockign and most functions are suspending. To take advantage of that, you need to pass the script as `suspend fun` and `CoroutineScope` as parameters to the suspending `shell` block.
165
+
113
166
#### in Kotlin code
114
-
with new coroutine scope:
167
+
With given scope:
115
168
```kotlin
116
-
shell {
169
+
shell (
170
+
scope = myScope
171
+
) {
117
172
"echo hello world!"()
118
173
}
119
174
```
120
175
121
-
with given scope:
176
+
With new coroutine scope:
122
177
```kotlin
123
-
shell (
124
-
scope = myScope
125
-
) {
178
+
shell {
126
179
"echo hello world!"()
127
180
}
128
181
```
182
+
183
+
129
184
#### in Kotlin Script
130
185
##### blocking api
131
186
The blocking api features basic shell commands without the need of wrapping it into coroutines calls:
@@ -135,7 +190,7 @@ The blocking api features basic shell commands without the need of wrapping it i
135
190
It can be accessed in Kotlin code as well by using `ScriptingShell` class.
136
191
137
192
##### non blocking api
138
-
The `shell()` function gives access to full api of `kotlin-shell`:
193
+
The `shell` block gives access to full api of `kotlin-shell`. It receives `GlobalScope` as implicit parameter:
139
194
```kotlin
140
195
shell {
141
196
"echo hello world!"()
@@ -185,8 +240,8 @@ To run equivalent process multiple times call `ProcessExecutable.copy()`
185
240
### pipelines
186
241
Pipelines can operate on processes, lambdas, files, strings, byte packages and streams.
187
242
188
-
#### piping logic
189
-
##### introduction
243
+
#### piping overview
244
+
##### piping introduction
190
245
Every executable element in Kotlin Shell receives its own `ExecutionContext`, which consist of `stdin`, `stdout` and `stderr` implemented as `Channels`. In the library channels are used under aliases `ProcessChannel`, `ProcessSendChannel` and `ProcessReceiveChannel` their unit is always `ByteReadPacket`. `Shell` itself is an `ExecutionContext` and provides default channels:
191
246
*`stdin` is always empty and closed `ProcessReceiveChannel`, which effectively acts like `/dev/null`. It It can be accessed elsewhere by `nullin` member.
192
247
*`stdout` is a rendezvous `ProcessSendChannel`, that passes everything to `System.out`.
@@ -304,6 +359,9 @@ shell {
304
359
```
305
360
306
361
### detaching
362
+
#### detaching overview
363
+
Detached process or pipeline is being executed asynchronous to the shell. It can be attached or awaited at any time. Also all of not-ended detached jobs will be awaited after the end of the script before finishig `shell` block.
364
+
307
365
#### detaching process
308
366
To detach process use `detach()` function:
309
367
```kotlin
@@ -350,18 +408,18 @@ To access detached processes use `detachedPipelines` member. It stores list of p
350
408
#### attaching
351
409
To attach detached job (process or pipeline) use `fg()`:
352
410
*`fg(Int)` accepting detached job id. By default it will use `1` as id.
353
-
*`fg(Process)`accepting detached process
354
-
*`fg(Pipeline)`accepting detached pipeline
411
+
*`fg(Process)` accepting detached process
412
+
*`fg(Pipeline)` accepting detached pipeline
355
413
356
414
To join all detached jobs call `joinDetached()`
357
415
358
-
### demonizing
416
+
### daemonizing
359
417
> At the current stage demonizing processes and pipelines is implemented in very unstable and experimental way.
360
418
>
361
419
> Though it should not be used.
362
420
363
421
### environment
364
-
Environment in Kotlin Shell is divided into two parts `shell environment` and `shell variables`. The environment from system is also inherited
422
+
Environment in Kotlin Shell is divided into two parts `shell environment` and `shell variables`. The environment from system is also copied.
365
423
366
424
To access the environment call:
367
425
*`environment` list or `env` command for `shell environment`
@@ -373,7 +431,7 @@ To access the environment call:
373
431
`system environment` is copied to `shell environment` at its creation. To access system environment any time call `systemEnv`
374
432
375
433
#### shell environment
376
-
`shell environment` is inherited by`Shell` from the system. It can be modified and is copied to sub shells.
434
+
`shell environment` is copied to`Shell` from the system. It can be modified and is copied to sub shells.
377
435
378
436
To set environment use `export`:
379
437
```kotlin
@@ -499,6 +557,7 @@ where `T` is desired return type or `Unit`. Such functions can be declared outsi
499
557
*`variables`
500
558
501
559
### sub shells
560
+
#### creating sub shells
502
561
To create sub shell use `shell` block:
503
562
```koltin
504
563
shell {
@@ -524,20 +583,49 @@ shell {
524
583
525
584
Sub shells suspend execution of the parent shell.
526
585
527
-
### dependencies
528
-
Kotlin Shell scripts support adding dependencies
586
+
#### sub shells use cases
587
+
Sub shell can be used to provide custom environment for commands:
588
+
```kotlin
589
+
shell {
590
+
export("KEY" to "ONE")
591
+
shell (
592
+
vars =mapOf("KEY" to "TWO")
593
+
) {
594
+
"echo ${env("KEY")} // TWO
595
+
}
596
+
597
+
// rest of the script
598
+
}
599
+
```
600
+
601
+
Or to temporarly change the directory:
602
+
```kotlin
603
+
shell {
604
+
"echo ${env("PWD")} // ../dir
605
+
606
+
shell (
607
+
dir = file("bin")
608
+
) {
609
+
"echo ${env("PWD")} // ../dir/bin
610
+
}
611
+
612
+
// rest of the script
613
+
}
614
+
```
529
615
530
-
Kotlin Shell uses dependencies mechanism from `kotlin-main-kts`.
616
+
### scripting specific features
617
+
#### dependencies
618
+
Kotlin Shell scripts support external and internal dependencies. The mechanism from `kotlin-main-kts` is being used. Learn more about it in [KEEP](https://github.com/Kotlin/KEEP/blob/master/proposals/scripting-support.md) and [blog post](https://blog.jetbrains.com/kotlin/2018/09/kotlin-1-3-rc-is-here-migrate-your-coroutines/#scripting).
531
619
532
-
#### external dependencies
620
+
##### external dependencies
533
621
External dependencies from maven repositories can be added via `@file:Repository` `@file:DependsOn` annotation:
534
622
```kotlin
535
623
@file:Repository("MAVEN_REPOSITORY_URL")
536
624
@file:DependsOn("GROUP:PACKAGE:VERSION")
537
625
```
538
626
then they can be imported with standard `import` statement.
539
627
540
-
#### internal dependencies
628
+
##### internal dependencies
541
629
To import something from local file use `@file:Import`:
0 commit comments