consolex 0.1.0

Windows console utilities: probe, create, and release the console of the current process, plus a small CLI.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# consolex

Windows console utilities: probe, create, and release the console of the
current process, plus a small CLI built on the library API.

Windows-only.

## Library

```toml
[dependencies]
consolex = "0.1"
```

The recommended usage is [`init`] with a [`Mode`] resolved from the
command-line flags. [`init`] returns `true` when a new console window was
created, which is your cue to pause so the window stays readable:

```rust
use consolex::{init, wait_key, Mode};

// Build the mode from the arguments: `--show` → Show, `--hide` → Hide,
// otherwise Auto. Any other arguments are ignored.
let mode: Mode = std::env::args_os().skip(1).collect();

let created = init(mode)?;
println!("hello from a console-aware program");

// Keep a newly created window open long enough to read the output.
if created {
    wait_key()?;
}
# Ok::<(), consolex::Error>(())
```

### Modes

| `Mode` | Behavior                                             | `init` returns |
| ------ | ---------------------------------------------------- | -------------- |
| `Auto` | Use the existing terminal, else create a window.     | `true` if a window was created |
| `Show` | Always create a new window.                          | `true`         |
| `Hide` | Detach the console; produce no output.               | `false`        |
| `Keep` | Leave the console state untouched.                   | `false`        |

### API

All names are short and explicit:

| Item            | Meaning                                        |
| --------------- | ---------------------------------------------- |
| `Mode`          | Desired console policy (`auto`/`show`/`hide`/`keep`), with `FromStr` and `FromIterator` impls. |
| `init(mode)`    | Apply a mode; returns whether a new window was created. |
| `wait_key`      | Block until a key is pressed (no-op on pipes). |
| `has_console`   | Is a console attached?                          |
| `set_mode(mode)`| Apply a mode (discards whether a window was created). |
| `attach`        | Use the parent terminal, else create a window.  |
| `show`          | Always create a new console window.             |
| `detach`        | Release the console if one is attached.         |

Errors are managed with [`thiserror`](https://crates.io/crates/thiserror):
`consolex::Error` with variants `Alloc`, `Free`, `Parse`, and `Input`.

Build your binary as a GUI-subsystem executable so no console flashes when a
third-party program launches it:

```rust
#![cfg_attr(windows, windows_subsystem = "windows")]
```

## CLI

The bundled `consolex` binary demonstrates the library. It is built as a
GUI-subsystem executable; console behavior is resolved at runtime:

| Launch context            | Behavior                                                      |
| ------------------------- | -------------------------------------------------------------- |
| Double-click              | A console opens showing the version info and waits for a key.  |
| From a terminal           | Version info goes to the existing console, then exits.         |
| Third-party, default      | A console is opened (no output is captured by the caller).     |
| `--hide`                  | Detaches the console and exits without output.                 |
| `--show`                  | Always opens a new console window.                             |

```text
Usage: consolex [OPTIONS]

Options:
      --show     Open a new console window
      --hide     Detach the console and exit without output
  -h, --help     Print help
  -V, --version  Print version
```

## Notes

- `has_console` uses `GetConsoleCP`, so consoles created with
  `CREATE_NO_WINDOW` (no visible window) are still detected correctly.
- `wait_key` temporarily disables line buffering and echo, restoring the
  original console mode afterwards, and returns immediately when standard
  input is redirected.