Skip to content

Commit

Permalink
finished documentation for release 0.7.1
Browse files Browse the repository at this point in the history
  • Loading branch information
@WeirdConstructor
WeirdConstructor committed May 25, 2021
1 parent b2a0d69 commit 8ab7088
Show file tree
Hide file tree
Showing 8 changed files with 394 additions and 14 deletions.
5 changes: 3 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
0.7.1 (unreleased)
0.7.1 (2021-05-25)
==================

* **Feature:** Added `std:process:spawn` and `std:process:kill_wait`.
* **Feature:** Added `std:process:wait` for waiting it to exit.
* **Feature:** Added `std:process:wait` and `std:process:try_wait`
for waiting it to exit.
* **Feature:** Calling into EvalContext::eval\*() can now be done
recursively.
* **Feature:** Added simple UDP networking via `std:net:udp:new`,
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "wlambda"
version = "0.7.1-beta1"
version = "0.7.1"
authors = ["Weird Constructor <[email protected]>"]
license = "GPL-3.0-or-later"
edition = "2018"
Expand Down
104 changes: 104 additions & 0 deletions doc/wlambda_reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,10 @@ Smalltalk, LISP and Perl.
- [11.2.5](#1125-stdnetudprecv-socket-byte-count) std:net:udp:recv _socket_ [_byte-count_]
- [11.3](#113-processes) Processes
- [11.3.1](#1131-stdprocessrun-executable-path-arguments) std:process:run _executable-path_ [_arguments_]
- [11.3.2](#1132-stdprocessspawn-executable-path-arg-vector-inheritout--inheritall) std:process:spawn _executable-path_ _arg-vector_ [:inherit\_out | :inherit\_all]
- [11.3.3](#1133-stdprocesstrywait-child-handle) std:process:try\_wait _child-handle_
- [11.3.4](#1134-stdprocesskillwait-child-handle) std:process:kill\_wait _child-handle_
- [11.3.5](#1135-stdprocesswait-child-handle) std:process:wait _child-handle_
- [11.4](#114-file-system) File System
- [11.4.1](#1141-stdfsrename-file-path-new-file-name) std:fs:rename _file-path_ _new-file-name_
- [11.4.2](#1142-stdfscopy-src-file-path-dst-file-path) std:fs:copy _src-file-path_ _dst-file-path_
Expand Down Expand Up @@ -7110,6 +7114,106 @@ std:assert_eq ret.stdout $b"test\n";
std:assert_eq ret.stderr $b"";
```

#### <a name="1132-stdprocessspawn-executable-path-arg-vector-inheritout--inheritall"></a>11.3.2 - std:process:spawn _executable-path_ _arg-vector_ [:inherit\_out | :inherit\_all]

Like `std:process:run` starts a process from the _executable-path_ and _arg-vector_.
But it does not wait until the process finished running, it returns a child process handle
or an error if something went wrong.

The handle can then be used by functions like:

* `std:process:kill_wait` - to kill and wait for the process to exit
* `std:process:try_wait` - to check if the process exited
* `std:process:wait` - to wait until the process exits

The third argument specifies what happens with the standard I/O file handles.
By default the child process gets _null_ handles, so neither output is captured
nor input is passed:

* _default_ - child process gets _null_ handles for stdin, stdout and stderr.
* `:inherit_out` - child process inherits stdout and stderr, but stdin will be _null_.
* `:inherit_all` - child process inherits all (stdout, stderr and stdin) from the
parent and uses them until it exits.

TODO: Implement pipe to/from the child process to be
read/written to via `std:io:read_some` and `std:io:write`.

```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
# do something in your program....
!result = unwrap ~ std:process:wait hdl;
std:assert ~ not result.success;
std:assert result.status == 20;
```

#### <a name="1133-stdprocesstrywait-child-handle"></a>11.3.3 - std:process:try\_wait _child-handle_

Checks if the child process behind _child-handle_ exited. Returns `$none` if
it did not exit yet. Returns a map with the structure
`${ status = ..., success = $true / $false }` if the child exited.
Or an error if something failed.

```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!counter = 0;
!ret = $none;
while $true {
std:thread:sleep :ms => 250;
.counter += 1;
.ret = unwrap ~ std:process:try_wait hdl;
if ret {
break ret;
};
};
std:assert counter > 0;
std:assert ~ not ret.success;
std:assert ret.status == 20;
```

#### <a name="1134-stdprocesskillwait-child-handle"></a>11.3.4 - std:process:kill\_wait _child-handle_

Kills the child process behind _child-handle_ and waits for it to return the exit status.
Returns a map with the structure `${ status = ..., success = $true / $false }` if the child exited.
Or an error if something failed.

```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!res = std:process:kill_wait hdl;
std:assert ~ not res.success;
std:assert_eq res.status -1;
```

#### <a name="1135-stdprocesswait-child-handle"></a>11.3.5 - std:process:wait _child-handle_

Waits until the child process behind _child-handle_ exits by itself.
Returns a map with the structure `${ status = ..., success = $true / $false }`
if the child exited. Or an error if something failed.

```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!res = std:process:wait hdl;
std:assert ~ not res.success;
std:assert_eq res.status 20;
```

### <a name="114-file-system"></a>11.4 - File System

#### <a name="1141-stdfsrename-file-path-new-file-name"></a>11.4.1 - std:fs:rename _file-path_ _new-file-name_
Expand Down
116 changes: 116 additions & 0 deletions src/cmdline_doc.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8043,6 +8043,122 @@
""
]
],
[
"11.3.2 - std:process:spawn _executable-path_ _arg-vector_ [:inherit_out | :inherit_all]",
[
"",
"Like `std:process:run` starts a process from the _executable-path_ and _arg-vector_.",
"But it does not wait until the process finished running, it returns a child process handle",
"or an error if something went wrong.",
"",
"The handle can then be used by functions like:",
"",
"* `std:process:kill_wait` - to kill and wait for the process to exit",
"* `std:process:try_wait` - to check if the process exited",
"* `std:process:wait` - to wait until the process exits",
"",
"The third argument specifies what happens with the standard I/O file handles.",
"By default the child process gets _null_ handles, so neither output is captured",
"nor input is passed:",
"",
"* _default_ - child process gets _null_ handles for stdin, stdout and stderr.",
"* `:inherit_out` - child process inherits stdout and stderr, but stdin will be _null_.",
"* `:inherit_all` - child process inherits all (stdout, stderr and stdin) from the",
"parent and uses them until it exits.",
"",
"TODO: Implement pipe to/from the child process to be",
"read/written to via `std:io:read_some` and `std:io:write`.",
"",
"```wlambda",
"!hdl = unwrap ~ std:process:spawn \"bash\" $[",
" \"-c\", \"for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20\"",
"];",
"",
"# do something in your program....",
"",
"!result = unwrap ~ std:process:wait hdl;",
"",
"std:assert ~ not result.success;",
"std:assert result.status == 20;",
"```",
""
]
],
[
"11.3.3 - std:process:try_wait _child-handle_",
[
"",
"Checks if the child process behind _child-handle_ exited. Returns `$none` if",
"it did not exit yet. Returns a map with the structure",
"`${ status = ..., success = $true / $false }` if the child exited.",
"Or an error if something failed.",
"",
"```wlambda",
"!hdl = unwrap ~ std:process:spawn \"bash\" $[",
" \"-c\", \"for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20\"",
"];",
"",
"!counter = 0;",
"!ret = $none;",
"while $true {",
" std:thread:sleep :ms => 250;",
" .counter += 1;",
"",
" .ret = unwrap ~ std:process:try_wait hdl;",
" if ret {",
" break ret;",
" };",
"};",
"",
"std:assert counter > 0;",
"std:assert ~ not ret.success;",
"std:assert ret.status == 20;",
"```",
""
]
],
[
"11.3.4 - std:process:kill_wait _child-handle_",
[
"",
"Kills the child process behind _child-handle_ and waits for it to return the exit status.",
"Returns a map with the structure `${ status = ..., success = $true / $false }` if the child exited.",
"Or an error if something failed.",
"",
"```wlambda",
"!hdl = unwrap ~ std:process:spawn \"bash\" $[",
" \"-c\", \"for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20\"",
"];",
"",
"!res = std:process:kill_wait hdl;",
"",
"std:assert ~ not res.success;",
"std:assert_eq res.status -1;",
"```",
""
]
],
[
"11.3.5 - std:process:wait _child-handle_",
[
"",
"Waits until the child process behind _child-handle_ exits by itself.",
"Returns a map with the structure `${ status = ..., success = $true / $false }`",
"if the child exited. Or an error if something failed.",
"",
"```wlambda",
"!hdl = unwrap ~ std:process:spawn \"bash\" $[",
" \"-c\", \"for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20\"",
"];",
"",
"!res = std:process:wait hdl;",
"",
"std:assert ~ not res.success;",
"std:assert_eq res.status 20;",
"```",
""
]
],
[
"11.4 - File System",
[
Expand Down
104 changes: 104 additions & 0 deletions src/prelude.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -379,6 +379,10 @@ Smalltalk, LISP and Perl.
- [11.2.5](#1125-stdnetudprecv-socket-byte-count) std:net:udp:recv _socket_ [_byte-count_]
- [11.3](#113-processes) Processes
- [11.3.1](#1131-stdprocessrun-executable-path-arguments) std:process:run _executable-path_ [_arguments_]
- [11.3.2](#1132-stdprocessspawn-executable-path-arg-vector-inheritout--inheritall) std:process:spawn _executable-path_ _arg-vector_ [:inherit\_out | :inherit\_all]
- [11.3.3](#1133-stdprocesstrywait-child-handle) std:process:try\_wait _child-handle_
- [11.3.4](#1134-stdprocesskillwait-child-handle) std:process:kill\_wait _child-handle_
- [11.3.5](#1135-stdprocesswait-child-handle) std:process:wait _child-handle_
- [11.4](#114-file-system) File System
- [11.4.1](#1141-stdfsrename-file-path-new-file-name) std:fs:rename _file-path_ _new-file-name_
- [11.4.2](#1142-stdfscopy-src-file-path-dst-file-path) std:fs:copy _src-file-path_ _dst-file-path_
Expand Down Expand Up @@ -7124,6 +7128,106 @@ std:assert_eq ret.stdout $b"test\n";
std:assert_eq ret.stderr $b"";
```
#### <a name="1132-stdprocessspawn-executable-path-arg-vector-inheritout--inheritall"></a>11.3.2 - std:process:spawn _executable-path_ _arg-vector_ [:inherit\_out | :inherit\_all]
Like `std:process:run` starts a process from the _executable-path_ and _arg-vector_.
But it does not wait until the process finished running, it returns a child process handle
or an error if something went wrong.
The handle can then be used by functions like:
* `std:process:kill_wait` - to kill and wait for the process to exit
* `std:process:try_wait` - to check if the process exited
* `std:process:wait` - to wait until the process exits
The third argument specifies what happens with the standard I/O file handles.
By default the child process gets _null_ handles, so neither output is captured
nor input is passed:
* _default_ - child process gets _null_ handles for stdin, stdout and stderr.
* `:inherit_out` - child process inherits stdout and stderr, but stdin will be _null_.
* `:inherit_all` - child process inherits all (stdout, stderr and stdin) from the
parent and uses them until it exits.
TODO: Implement pipe to/from the child process to be
read/written to via `std:io:read_some` and `std:io:write`.
```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
# do something in your program....
!result = unwrap ~ std:process:wait hdl;
std:assert ~ not result.success;
std:assert result.status == 20;
```
#### <a name="1133-stdprocesstrywait-child-handle"></a>11.3.3 - std:process:try\_wait _child-handle_
Checks if the child process behind _child-handle_ exited. Returns `$none` if
it did not exit yet. Returns a map with the structure
`${ status = ..., success = $true / $false }` if the child exited.
Or an error if something failed.
```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!counter = 0;
!ret = $none;
while $true {
std:thread:sleep :ms => 250;
.counter += 1;
.ret = unwrap ~ std:process:try_wait hdl;
if ret {
break ret;
};
};
std:assert counter > 0;
std:assert ~ not ret.success;
std:assert ret.status == 20;
```
#### <a name="1134-stdprocesskillwait-child-handle"></a>11.3.4 - std:process:kill\_wait _child-handle_
Kills the child process behind _child-handle_ and waits for it to return the exit status.
Returns a map with the structure `${ status = ..., success = $true / $false }` if the child exited.
Or an error if something failed.
```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!res = std:process:kill_wait hdl;
std:assert ~ not res.success;
std:assert_eq res.status -1;
```
#### <a name="1135-stdprocesswait-child-handle"></a>11.3.5 - std:process:wait _child-handle_
Waits until the child process behind _child-handle_ exits by itself.
Returns a map with the structure `${ status = ..., success = $true / $false }`
if the child exited. Or an error if something failed.
```wlambda
!hdl = unwrap ~ std:process:spawn "bash" $[
"-c", "for i in `seq 0 10`; do echo $i; sleep 0.2; done; exit 20"
];
!res = std:process:wait hdl;
std:assert ~ not res.success;
std:assert_eq res.status 20;
```
### <a name="114-file-system"></a>11.4 - File System
#### <a name="1141-stdfsrename-file-path-new-file-name"></a>11.4.1 - std:fs:rename _file-path_ _new-file-name_
Expand Down
Loading

0 comments on commit 8ab7088

Please sign in to comment.