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 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
//! # Windows Powershell script runner
//!
//! This crate is pretty basic. It uses `std::process::Command` to pipe commands
//! to PowerShell. In addition to that there is a convenient wrapper around `process::Output`
//! especially tailored towards the usecase of running Windows PowerShell commands.
//!
//! ## Example
//!
//! I recommend that you write the commands to a `*.ps` file to be able to take advantage
//! of existing tools to create the script.
//!
//! This example creates a shortcut of `notepad.exe` to the desktop.
//!
//! **In `script.ps`**
//! ```ps
//! $SourceFileLocation="C:\Windows\notepad.exe"
//! $ShortcutLocation=[Environment]::GetFolderPath("Desktop")+"\notepad.lnk"
//! $WScriptShell=New-Object -ComObject WScript.Shell
//! $Shortcut=$WScriptShell.CreateShortcut($ShortcutLocation)
//! $Shortcut.TargetPath=$SourceFileLocation
//! $Shortcut.Save()
//! ```
//!
//! **In `main.rs`**
//! ```rust, ignore
//! use crate powershell_script;
//!
//! // Creates a shortcut to notpad on the desktop
//! fn main() {
//! let create_shortcut = include_str!("script.ps");
//! match powershell_script::run(create_shortcut) {
//! Ok(output) => {
//! println!("{}", output);
//! }
//! Err(e) => {
//! println!("Error: {}", e);
//! }
//! }
//! }
//! ```
//!
//! You can of course provide the commands as a string literal instead. Just beware that
//! we run each `line` as a separate command.
//!
//! The flag `print_commands` can be set to `true` if you want each
//! command to be printed to the `stdout` of the main process as they're run which
//! can be useful for debugging scripts or displaying the progress.
//!
//! ## Use the `PsScriptBuilder` for better control
//!
//! Instead of running a script using `powershell_script::run()` you can use
//! `PsScriptBuilder` to configure several options:
//!
//! ```
//! use powershell_script::PsScriptBuilder;
//!
//! fn main() {
//! let ps = PsScriptBuilder::new()
//! .no_profile(true)
//! .non_interactive(true)
//! .hidden(false)
//! .print_commands(false)
//! .build();
//! let output = ps.run(r#"echo "hello world""#).unwrap();
//!
//! assert!(output.stdout().unwrap().contains("hello world"));
//! }
//! ```
//!
//! ## Features and compatability
//!
//! On Windows it defaults to using the PowerShell which ships with Windows, but you
//! can also run scripts using PowerShell Core on Windows by enabling the
//! `core` feature.
//!
//! On all other operating systems it will run scripts using PowerShell core.
//!
mod builder;
mod error;
mod output;
mod target;
// Note: PowerShell Core can be isntalled on windows as well so we can't simply
// discriminate based on target family.
#[cfg(all(not(feature = "core"), windows))]
/// Windows PowerShell
const POWERSHELL_NAME: &str = "PowerShell.exe";
#[cfg(any(feature = "core", not(windows)))]
/// PowerShell Core
const POWERSHELL_NAME: &str = "pwsh.exe";
type Result<T> = std::result::Result<T, PsError>;
#[cfg(target_family = "unix")]
pub use target::unix::PsScript;
#[cfg(target_family = "windows")]
pub use target::windows::PsScript;
pub use {builder::PsScriptBuilder, error::PsError, output::Output};
/// Runs a script in PowerShell. Returns an instance of `Output`. In the case of
/// a failure when running the script it returns an `PsError::Powershell(Output)`
/// which holds the output object containing the captures of `stderr` and `stdout`
/// for display. The flag `print_commands` can be set to `true` if you want each
/// command to be printed to the `stdout` of the main process as they're run. Useful
/// for debugging scripts.
///
/// ## Panics
/// If there is an error retrieving a handle to `stdin` in the child process.
///
/// ## Example
///
/// ```rust
/// fn main() {
/// let script = r#"echo "hello world""#;
/// let output = powershell_script::run(script).unwrap();
/// assert_eq!(output.stdout().unwrap().trim(), "hello world");
/// }
/// ```
///
pub fn run(script: &str) -> Result<Output> {
PsScriptBuilder::default().build().run(script)
}