ut/README.md

# ut package

The ut package exposes some utilities the subpackage [utio](utio) exposes some IO related utilities. The package is licensed under [MIT](LICENSE). Currently this package is still under development and thus the API may break.

## API

Packages:
 - [ut](#ut-package)
 - [utio](#utio-package)

### ut package

**Deopter**

`Deopter` may be used an action may or may not be executed. Particularly useful in combination with defer.

Example:
```
function Open(p string) (*File, error) {
    var f, _ = os.Open(p)
    var d = NewDeopter(f.Close)
    defer d.Invoke()

    var err error
    // code that might exit early    
    if nil != err {
        return nil, err
    }

    // successful code path
    d.Deopt()
    return f
}
```

**Errors**

An `Errors` struct that represents multiple errors (but still adheres to the `error` interface)

```
type Errors struct {
	Errs []error
}
```

Combine errors using `ErrCombine` when you want to combine multiple errors as one. Makes use of the `Errors` interface when there is more than one error.
```
var err error
err = ErrCombine(err, err2)
```

### utio package

Encoder/decoder interfaces and two implementations:
 - JSON
 - PNG

```
type Decoder interface {
    Decode(io.Reader) error
}

type Encoder interface {
    Encode(io.Writer) error
}
```

Utility methods for reading/writing (with or without encoding) files and strings.

```
// File methods
func DecodeFile(string, Decoder) error
func ReadFile(string, ReadFunc) error

func EncodeFile(string, Encoder) error
func WriteFile(string, WriteFunc) error

// String methods
func DecodeFromString(string, Decoder) error
func ReadFromString(string, ReadFunc) error

func EncodeToString(Encoder) (string, error)
func WriteToString(WriteFunc) (string, error)
```

Utility methods related to the os/file system.
```
func Home() (string, error) // returns the user directory
func PathExists(string) bool
func PathDoesNotExist(string) bool
```