effdump

README

effdump

effdump is a Go module to generate and diff textual effects across git commits. See https://pkg.go.dev/github.com/ypsu/effdump for the documentation.

Note: this project uses https://ypsu.github.io/featver as its versioning scheme. The project will enter the more stable v1 version only when it has users already.

Documentation

Overview

Package effdump implements the CLI tool for working with effdumps.

effdump testing is like output or golden testing but the outputs don't have to be committed into the git repository. It can render the diffs both in unified and HTML format and deduplicates the individual diffs. Convenient CLI usage is the module's main design goal.

To use it create a new dump with New, Dump.Add a bunch of key/value pairs, and call Dump.Run. effdump takes over the rest, it makes the package into a CLI tool. See

• https://github.com/ypsu/effdump/tree/main/example-markdown/README.md
• https://github.com/ypsu/effdump/tree/main/example-deployment/README.md

for how exactly it works. See the testing part of https://github.com/ypsu/pkgtrim for a more realistic example.

Index

• func AddMap[M ~map[K]V, K comparable, V any](d *Dump, m M)
• type Dump
  • func New(name string) *Dump
  • func (d *Dump) Add(key, value any)
  • func (d *Dump) Hash() uint64
  • func (d *Dump) RegisterFlags(fs *flag.FlagSet)
  • func (d *Dump) Run(ctx context.Context)
  • func (d *Dump) SetVersionSystem(vs VersionSystem)
• type VersionSystem

Functions

func AddMap

func AddMap[M ~map[K]V, K comparable, V any](d *Dump, m M)

AddMap adds each entry of the map to the dump. The keys and values are stringified the same way as in [Add]. It's a standalone method due to a Go limitation around generics.

Types

type Dump

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

Dump represesents an effdump.

func New

func New(name string) *Dump

New initializes a new Dump.

func (*Dump) Add

func (d *Dump) Add(key, value any)

Add adds a key value into the dump. The key and value are automatically stringified. It stringifies structs and lists without a String() function into json.

func (*Dump) Hash

func (d *Dump) Hash() uint64

Hash hashes the values in the dump. Returns the same value as the hash subcommand. Returns 0 if there are duplicated keys in the dump.

func (*Dump) RegisterFlags

func (d *Dump) RegisterFlags(fs *flag.FlagSet)

RegisterFlags registers effdump's flags into a flagset. If not called, flags are autoregistered into flag.CommandLine in Run(). Usage example:

d := effdump.New("mydump")
d.RegisterFlags(flag.CommandLine)
myflag := flag.String("custominput", "", "If specified, runs mydump with this custom input.")
flag.Parse()
if *myflag { ... }
...
d.Run(ctx)

func (*Dump) Run

func (d *Dump) Run(ctx context.Context)

Run implements the CLI interface. This is meant to overtake the main() function: this function never returns.

func (*Dump) SetVersionSystem

func (d *Dump) SetVersionSystem(vs VersionSystem)

SetVersionSystem overrides the version control system effdump uses. The default is git if this function isn't called.

type VersionSystem

type VersionSystem interface {
	// HasChanges tells effdump whether the current directory has changes compared the HEAD revision.
	// effdump uses this to determine the default action when used with no-args mode.
	HasChanges(context.Context) (dirty bool, err error)

	// Resolve references like "HEAD" and "HEAD^" to a version.
	// effdump passes empty revision to look up the current HEAD.
	// The returned version should be alphanumeric because it's going to be used as filenames.
	Resolve(ctx context.Context, revision string) (version string, err error)
}

VersionSystem resolves source code versions from the current environment.