gopwsh

README

gopwsh

Package gopwsh is a simple host for PowerShell with-in your Go code.

Originally inspired by https://github.com/bhendo/go-powershell

Quick Start

go get -u github.com/brad-jones/gopwsh

package main

import (
	"fmt"

	"github.com/brad-jones/gopwsh"
)

func main() {
	shell := gopwsh.MustNew()
	defer shell.Exit()
	stdout, _, err := shell.Execute("Get-ComputerInfo")
	if err != nil {
		panic(err)
	}
	fmt.Println(stdout)
}

Also see further working examples under: https://github.com/brad-jones/gopwsh/tree/master/examples

Cross Platform Support

PowerShell these days of course is a cross platform shell, able to run on Windows, MacSO & Linux.

This go module should in theory work on all those platforms too.

But (at this stage) has not been tested anywhere apart from Windows. Who uses PowerShell outside of Windows... sorry thats short sighted & naive of me.

Eventually I'll get around to writing a full test suite but until then if you are one of these users & notice a bug, PRs are of course welcome :)

Documentation

Index

• func Backend(b Starter) func(*Shell) error
• func Elevated(sudoLocation ...string) func(*Shell) error
• func Env(env map[string]string) func(*Shell) error
• func EnvCombined(v bool) func(*Shell) error
• func PwshLocation(path string) func(*Shell) error
• func QuoteArg(s string) string
• func WorkingDir(wd string) func(*Shell) error
• type Shell
  • func MustNew(decorators ...func(*Shell) error) *Shell
  • func New(decorators ...func(*Shell) error) (s *Shell, err error)
  • func (s *Shell) Execute(cmds ...string) (string, string, error)
  • func (s *Shell) Exit()
  • func (s *Shell) MustExecute(cmds ...string) (string, string)
• type Starter

Functions

func Backend

func Backend(b Starter) func(*Shell) error

Backend allows you set a custom backend or "Starter".

func Elevated

func Elevated(sudoLocation ...string) func(*Shell) error

Elevated will create an elevated PowerShell process. This functionality assumes a "sudo" command exists on the system.

On *nix systems this can probably be taken for granted. On Windows systems a package like the following should be installed:

* https://github.com/gerardog/gsudo * https://github.com/brad-jones/winsudo

Calling this function without any arguments, tells us you want an elevated session & we will do our best to locate a "sudo" binary for you. Otherwise you may provide a single argument of the path to a "sudo" binary.

func Env

func Env(env map[string]string) func(*Shell) error

Env allows you to set custom environment variable for the PowerShell process.

func EnvCombined

func EnvCombined(v bool) func(*Shell) error

EnvCombined is set to true will instruct the backend to combine these variables with the ones already define on the backend's environments.

func PwshLocation

func PwshLocation(path string) func(*Shell) error

PwshLocation allows you supply a custom path to a PowerShell executeable.

func QuoteArg

func QuoteArg(s string) string

QuoteArg can be used to escape string literals that you want to ensure don't get mangled between your Go code and PowerShell.

func WorkingDir

func WorkingDir(wd string) func(*Shell) error

WorkingDir allows you to set a custom initial working directory for the PowerShell process.

Types

type Shell

type Shell struct {
	// contains filtered or unexported fields
}

Shell is the primary object that represents a running PowerShell process.

Create new instances of this with the "New()" function.

func MustNew

func MustNew(decorators ...func(*Shell) error) *Shell

MustNew is the same as New but panics on error instead of returning an error.

func New

func New(decorators ...func(*Shell) error) (s *Shell, err error)

New is a constructor like function for the Shell struct.

All configuration is done through the functional options pattern. see: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis

e.g:

gopwsh.New(gopwsh.PwshLocation("/some/path/pwsh.exe"), ...)

Some Defaults

If no backend is set we will use the Local one.

If no pwshLocation is set we will use the backend's LookPath method to first look for an executebale named "pwsh". On failure of that we will look for an executable named "powershell".

envCombined is set to true

func (*Shell) Execute

func (s *Shell) Execute(cmds ...string) (string, string, error)

Execute is what you can use to actually execute arbitrary powershell commands & script.

It will return the STDOUT & STDERR in 2 separate strings. Even if STDERR is not empty then the err value will still be nil. Only errors associated with this gopwsh module will be returned.

Just because a command returns STDERR doesn't necessarily mean failure. ie: some commands log progress messages / extra debugging info to STDERR but still successfully perform their task.

ParserErrors are however considered fatal and will result in an error value being returned. The underlying PowerShell process will be killed and you won't be able to use this instance of the Shell any longer.

func (*Shell) Exit

func (s *Shell) Exit()

Exit is used to kill the powershell process.

Typical usage might look like:

shell := gopwsh.New()
defer shell.Exit()

func (*Shell) MustExecute

func (s *Shell) MustExecute(cmds ...string) (string, string)

MustExecute is the same as Execute but panics on error instead of returning an error.

type Starter

type Starter interface {
	LookPath(file string) (string, error)
	SetEnv(values map[string]string, combined bool)
	SetWorkingDir(v string)
	StartProcess(cmd string, args ...string) error
	Stderr() io.Reader
	Stdin() io.Writer
	Stdout() io.Reader
	Wait() error
}

Starter describes what we use to actually "start" a powershell process.

This module includes an implementation for running processes locally. Other implementations such as starting a process via SSH are possible but "at this stage" are left as an exercise for the reader - PRs welcome :)