README.md

Documentation: oss.terrastruct.com/util-go

     1# util-go
     2
     3[![godoc](https://pkg.go.dev/badge/oss.terrastruct.com/util-go.svg)](https://pkg.go.dev/oss.terrastruct.com/util-go)
     4[![ci](https://github.com/terrastruct/util-go/actions/workflows/ci.yml/badge.svg)](https://github.com/terrastruct/util-go/actions/workflows/ci.yml)
     5[![daily](https://github.com/terrastruct/util-go/actions/workflows/daily.yml/badge.svg)](https://github.com/terrastruct/util-go/actions/workflows/daily.yml)
     6[![license](https://img.shields.io/github/license/terrastruct/util-go?color=9cf)](./LICENSE)
     7
     8Terrastruct's general purpose go libraries.
     9
    10See https://pkg.go.dev/oss.terrastruct.com/util-go for docs.
    11
    12If there's enough external demand for a single package to be split off into its
    13own repo from this collection we will. Feel free to open an issue to request.
    14
    15<!-- toc -->
    16- [./diff](#diff)
    17- [./assert](#assert)
    18- [./xdefer](#xdefer)
    19- [./cmdlog](#cmdlog)
    20- [./xterm](#xterm)
    21- [./xos](#xos)
    22- [./xrand](#xrand)
    23- [./xcontext](#xcontext)
    24- [./xjson](#xjson)
    25- [./go2](#go2)
    26- [./xbrowser](#xbrowser)
    27- [./xexec](#xexec)
    28- [./xhttp](#xhttp)
    29- [./xmain](#xmain)
    30- [./mapfs](#mapfs)
    31
    32godoc is the canonical reference but we've provided this index as the godoc UI is frankly
    33garbage after the move to pkg.go.dev. It's nowhere near as clear and responsive as the old
    34UI. If this feedback reaches the authors of pkg.go.dev, please revert the UI back to what
    35it was with godoc.org.
    36
    37### [./diff](./diff)
    38
    39diff providers functions to diff strings, files and general Go values with git diff.
    40
    41### [./assert](./assert)
    42
    43assert provides test assertion helpers. It integrates with [./diff](#diff) to display
    44beautiful diffs.
    45
    46note: `TestdataJSON` is extremely useful.
    47
    48![example output](./diff/example.png)
    49
    50- Strings
    51- Files
    52- Runes
    53- JSON
    54- Testdata
    55- TestdataJSON
    56
    57### [./xdefer](./xdefer)
    58
    59xdefer annotates all errors returned from a function transparently.
    60
    61### [./cmdlog](./cmdlog)
    62
    63cmdlog implements color leveled logging for command line tools.
    64
    65![example output](./cmdlog/example/example.png)
    66
    67`cmdlog` supports arbitrary randomly colored prefixes just like
    68[terrastruct/ci](https://github.com/terrastruct/ci).
    69
    70Example is in [./cmdlog/example/main.go](./cmdlog/example/main.go).
    71
    72See [./cmdlog/cmdlog_test.go](./cmdlog/cmdlog_test.go) for further usage.
    73
    74You can log in tests with `NewTB`.
    75
    76- `$COLOR` is obeyed to force enable/disable colored output.
    77- `$DEBUG` is obeyed to enable/disable debug logs.
    78
    79### [./xterm](./xterm)
    80
    81xterm implements outputting formatted text to a terminal.
    82
    83### [./xos](./xos)
    84
    85xos provides OS helpers.
    86
    87### [./xrand](./xrand)
    88
    89xrand provides helpers for generating useful random values.
    90We use it mainly for generating inputs to tests.
    91
    92### [./xcontext](./xcontext)
    93
    94xcontext implements indispensable context helpers.
    95
    96### [./xjson](./xjson)
    97
    98xjson implements basic JSON helpers.
    99
   100### [./go2](./go2)
   101
   102go2 contains general utility helpers that should've been in Go. Maybe they'll be in Go 2.0.
   103
   104### [./xbrowser](./xbrowser)
   105
   106xbrowser enables opening a user's GUI browser to a URL.
   107
   108### [./xexec](./xexec)
   109
   110xexec provides exec helpers.
   111
   112### [./xhttp](./xhttp)
   113
   114xhttp provides HTTP helpers.
   115
   116### [./xmain](./xmain)
   117
   118xmain implements helpers for building CLI tools.
   119
   120### [./mapfs](./mapfs)
   121
   122Package mapfs takes in a description of a filesystem as a `map[string]string` and writes it to a temp directory so that it may be used as an io/fs.FS.
View as plain text