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
91
125
Kotlin Shell scripts have `sh.kts` extension.
92
126
93
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
+
```
120
161
121
162
## usage
122
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
+
123
166
#### in Kotlin code
124
-
with new coroutine scope:
167
+
With given scope:
125
168
```kotlin
126
-
shell {
169
+
shell (
170
+
scope = myScope
171
+
) {
127
172
"echo hello world!"()
128
173
}
129
174
```
130
175
131
-
with given scope:
176
+
With new coroutine scope:
132
177
```kotlin
133
-
shell (
134
-
scope = myScope
135
-
) {
178
+
shell {
136
179
"echo hello world!"()
137
180
}
138
181
```
182
+
183
+
139
184
#### in Kotlin Script
140
185
##### blocking api
141
186
The blocking api features basic shell commands without the need of wrapping it into coroutines calls:
@@ -145,7 +190,7 @@ The blocking api features basic shell commands without the need of wrapping it i
145
190
It can be accessed in Kotlin code as well by using `ScriptingShell` class.
146
191
147
192
##### non blocking api
148
-
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:
149
194
```kotlin
150
195
shell {
151
196
"echo hello world!"()
@@ -195,8 +240,8 @@ To run equivalent process multiple times call `ProcessExecutable.copy()`
195
240
### pipelines
196
241
Pipelines can operate on processes, lambdas, files, strings, byte packages and streams.
197
242
198
-
#### piping logic
199
-
##### introduction
243
+
#### piping overview
244
+
##### piping introduction
200
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:
201
246
*`stdin` is always empty and closed `ProcessReceiveChannel`, which effectively acts like `/dev/null`. It It can be accessed elsewhere by `nullin` member.
202
247
*`stdout` is a rendezvous `ProcessSendChannel`, that passes everything to `System.out`.
@@ -314,6 +359,9 @@ shell {
314
359
```
315
360
316
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
+
317
365
#### detaching process
318
366
To detach process use `detach()` function:
319
367
```kotlin
@@ -360,18 +408,18 @@ To access detached processes use `detachedPipelines` member. It stores list of p
360
408
#### attaching
361
409
To attach detached job (process or pipeline) use `fg()`:
362
410
*`fg(Int)` accepting detached job id. By default it will use `1` as id.
363
-
*`fg(Process)`accepting detached process
364
-
*`fg(Pipeline)`accepting detached pipeline
411
+
*`fg(Process)` accepting detached process
412
+
*`fg(Pipeline)` accepting detached pipeline
365
413
366
414
To join all detached jobs call `joinDetached()`
367
415
368
-
### demonizing
416
+
### daemonizing
369
417
> At the current stage demonizing processes and pipelines is implemented in very unstable and experimental way.
370
418
>
371
419
> Though it should not be used.
372
420
373
421
### environment
374
-
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.
375
423
376
424
To access the environment call:
377
425
*`environment` list or `env` command for `shell environment`
@@ -383,7 +431,7 @@ To access the environment call:
383
431
`system environment` is copied to `shell environment` at its creation. To access system environment any time call `systemEnv`
384
432
385
433
#### shell environment
386
-
`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.
387
435
388
436
To set environment use `export`:
389
437
```kotlin
@@ -509,6 +557,7 @@ where `T` is desired return type or `Unit`. Such functions can be declared outsi
509
557
*`variables`
510
558
511
559
### sub shells
560
+
#### creating sub shells
512
561
To create sub shell use `shell` block:
513
562
```koltin
514
563
shell {
@@ -534,20 +583,49 @@ shell {
534
583
535
584
Sub shells suspend execution of the parent shell.
536
585
537
-
### dependencies
538
-
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
+
```
539
615
540
-
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).
541
619
542
-
#### external dependencies
620
+
##### external dependencies
543
621
External dependencies from maven repositories can be added via `@file:Repository` `@file:DependsOn` annotation:
544
622
```kotlin
545
623
@file:Repository("MAVEN_REPOSITORY_URL")
546
624
@file:DependsOn("GROUP:PACKAGE:VERSION")
547
625
```
548
626
then they can be imported with standard `import` statement.
549
627
550
-
#### internal dependencies
628
+
##### internal dependencies
551
629
To import something from local file use `@file:Import`:
0 commit comments