goshell

README

goshell

Tricky and fun utilities for Go programs.

---

---

Getting Started

Prerequisites

• Go
• Git
• GitHub CLI

Developed with $( go version; ). Go is extremely backwards compatible and semver stable. Nearly any v1.x should work fine.

---

Installation

To use this repo as a template for your own project:

gh repo create -y --public --template "https://github.com/skeptycal/goshell"

Clone this repo to test and contribute:

# add repo to $GOPATH (xxxxxx is your computer login username)
go get github.com/xxxxxx/goshell

cd ${GOPATH}/src/github.com/xxxxxx/goshell

# test results and coverage info
./go.test.sh

# install as a utility package
go install

Use the Issues and PR templates on the GitHub repo page to contribute.

---

Basic Usage

This is a copy of the example script available in the cmd/example/goshell folder:

package main

import "github.com/skeptycal/goshell"

func main() {
    goshell.Example()
}

To try it out:

# change to the sample folder
cd cmd/example/goshell

# run the main.go program
go run ./main.go

# to compile as an executable
go build

---

Code of Conduct and Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Please read the Code of Conduct for details before submitting anything.

---

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

---

Contributors and Inspiration

• Michael Treanor (GitHub / Twitter) - Initial work, updates, maintainer
• Francesc Campoy - Inspiration and great YouTube videos!

See also the list of contributors who participated in this project.

---

License

Licensed under the MIT https://opensource.org/licenses/MIT - see the LICENSE file for details.

Documentation

Index

• Variables
• func CanUpdate(v interface{}) bool
• func EnvMap() map[string]string
• func Environ() []string
• func Example()
• func Expand(path string) (string, error)
• func GetHomeDir() (string, error)
• func Getenv(envVarName string, defaultValue string) (retval string)
• func MustSet(ptr interface{})
• func Reset()
• func Set(ptr interface{}) error
• func Setenv(key, value string) error
• func Shell(commands ...string) (string, string, error)
• func ShellPool(args ...string) (string, string, error)
• type Dir
  • func NewHome() Dir
• type GetSetter
• type Setter

Variables

var DisableCache bool

/ ------------------------------------------------------ old version DisableCache will disable caching of the home directory. Caching is enabled by default.

var (
	HOME = NewHome
)

Functions

func CanUpdate

func CanUpdate(v interface{}) bool

CanUpdate returns true when the given value is an initial value of its type

func EnvMap

func EnvMap() map[string]string

EnvMap returns a mapping of string keys to string values representing the environment, in the form "m[key] == value", e.g.

home := m["HOME"]
fmt.Println(home)
// /Users/skeptycal/

func Environ

func Environ() []string

Environ returns a copy of strings representing the environment, in the form "key=value".

func Example

func Example()

func Expand

func Expand(path string) (string, error)

Expand expands the path to include the home directory if the path is prefixed with `~`. If it isn't prefixed with `~`, the path is returned as-is.

func GetHomeDir

func GetHomeDir() (string, error)

GetHomeDir returns the home directory for the executing user.

This uses an OS-specific method for discovering the home directory. An error is returned if a home directory cannot be detected.

func Getenv

func Getenv(envVarName string, defaultValue string) (retval string)

Getenv returns the value of the string while replaces ${var} or $var in the string according to the values of the current environment variables. References to undefined variables are replaced by defaultValue.

d := Getenv("${HOME}/.config")
fmt.Println(d)
// /Users/skeptycal/.config

func MustSet

func MustSet(ptr interface{})

MustSet function is a wrapper of Set function It will call Set and panic if err not equals nil.

func Reset

func Reset()

Reset clears the cache, forcing the next call to Dir to re-detect the home directory. This generally never has to be called, but can be useful in tests if you're modifying the home directory via the HOME env var or something.

func Set

func Set(ptr interface{}) error

Set initializes members in a struct referenced by a pointer. Maps and slices are initialized by `make` and other primitive types are set with default values. `ptr` should be a struct pointer

func Setenv

func Setenv(key, value string) error

Setenv sets the value of the environment variable named by the key. It returns an error, if any.

func Shell

func Shell(commands ...string) (string, string, error)

ShBuffered executes the named shell command and returns stdout, stderr, and any error that occurred.

The buffers for the command outputs are standard bytes.Buffers and may not be performant for multiple repeated commands. See ShellPool.

The default timeout is 10 seconds.

func ShellPool

func ShellPool(args ...string) (string, string, error)

ShellPool executes the named shell command and returns stdout, stderr, and any error that occurred.

The buffers for the command outputs are sync.Pool bytes.Buffers and are safe for concurrent use and streamlined for high performance.

The default timeout is 10 seconds.

Types

type Dir

type Dir interface {
	Abs() string
	Base() string
	Reset()
	SetCache(disabled bool)
}

func NewHome

func NewHome() Dir

type GetSetter

type GetSetter interface {
}

Setter is an interface for setting default values

type Setter

type Setter interface {
	SetDefaults()
}

Setter is an interface for setting default values