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
// Copyright 2021 Foxcirc.
//
// Licensed under he MIT license: https://opensource.org/licenses/MIT
//! Create multiple consoles for a **windows** application.
//!
//! This crate makes use of windows Named Pipes to enable a process
//! to controll multiple consoles.
//!
//! # Quick Overview
//!
//! Normaly a program running on windows can only use one console.
//! > A process can be associated with only one console, so the AllocConsole
//! > function fails if the calling process already has a console.
//!
//! _From the [microsoft docs]._
//!
//! This crate solves this problem by providing an abstraction over a worker process
//! wich is controlled using named pipes.
//!
//! # Examples
//!
//! You can use the [`Console`] class to create a new console, after that
//! you can write to it or read a line.
//! It is planned, that [`Console`] will also implement the `Read` and `Write` traits.
//!
//! ```rust
//! use pipedconsole::Console;
//!
//! let my_console = Console::new("My Console").expect("Failed to create a new console");
//! my_console.println("What is your name?"); // seperate window
//!
//! let mut name = String::new();
//! my_console.read_line(&mut name).expect("Could not read from the console");
//! println!("Your name is: {}", name); // main processe's console
//! ```
//! When the console object is dropped or the calling program exits, the console
//! will close automaticly, unless another process also writes to it.
//!
//! # Important
//! This crate comes with a build script wich tries to compile the `console_worker` executable.
//! You need to have the `cargo` command usable in order for it to work.
//! This script is important because cargo does not build binaries inside library crates, so
//! it needs to be done manually.
//!
//! If the build script runs for the first time, it will display an info message.
//!
//! When you run your program, a call to `Console::new` will do the following:
//!
//! 1. It trys to find the `console_worker` executable **in the same directory** as the currently running one.
//! This will always work, if you put `console_worker.exe` into the same folder as any executable calling Console::new().
//! 2. If it cant find the executable, it tries to find it at the default path cargo will put it when you build normally.
//! This only works inside the default cargo project structure and makes it easier to just use this crate as-is.
//!
//! If you want to move your executable and run it in a new directory because of some reason,
//! you will have to find `console_worker.exe` on your computer.
//! For more information on where you can find it, run the build script again with the `PIPED_CONSOLE_HELP`
//! environment variable set.
//!
//! If you use `cmd`:
//!
//! ```
//! set PIPED_CONSOLE_HELP=TRUE
//! cargo clean
//! cargo build
//! ```
//!
//! This should display a message on where the `console_worker` executable is located.
//!
//! # Additional Information
//!
//! Creating a new [`Console`] **will create a new seperate process**. That means you will
//! see a "console_worker" process in your task manager. That process is just the console
//! listening for commands to execute.
//!
//! In order to interface to a console-worker process using another language etc. you can
//! manually launch it and then connect to the named pipe wich is created. For more
//! information about this see the `worker` documentation inside the repository.
//! You can find the worker binary files at `/src/bin/console_worker/main.rs`
//!
//! [microsoft docs]: https://docs.microsoft.com/en-us/windows/console/allocconsole
#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#[doc(hidden)]
pub(crate) mod com;
pub(crate) mod error;
mod console;
pub use console::Console;
pub use error::{ConsoleError as Error, ErrorKind};