miller/pkg/transformers/bar.go

package transformers

import (
	"bytes"
	"fmt"
	"os"
	"strings"

	"github.com/johnkerl/miller/v6/pkg/cli"
	"github.com/johnkerl/miller/v6/pkg/mlrval"
	"github.com/johnkerl/miller/v6/pkg/types"
)

const barDefaultFillString = "*"
const barDefaultOOBString = "#"
const barDefaultBlankString = "."
const barDefaultLo = 0.0
const barDefaultHi = 100.0
const barDefaultWidth = int64(40)

const verbNameBar = "bar"

var barOptions = []OptionSpec{
	{Flag: "-f", Arg: "{a,b,c}", Type: "csv-list", Desc: "Field names to convert to bars."},
	{Flag: "--lo", Arg: "{lo}", Type: "float", Desc: "Lower-limit value for min-width bar: default '0.000000'."},
	{Flag: "--hi", Arg: "{hi}", Type: "float", Desc: "Upper-limit value for max-width bar: default '100.000000'."},
	{Flag: "-w", Arg: "{n}", Type: "int", Desc: "Bar-field width: default '40'."},
	{Flag: "--auto", Type: "bool", Desc: "Automatically computes limits, ignoring --lo and --hi. Holds all records in memory before producing any output."},
	{Flag: "-c", Arg: "{character}", Type: "string", Desc: "Fill character: default '*'."},
	{Flag: "-x", Arg: "{character}", Type: "string", Desc: "Out-of-bounds character: default '#'."},
	{Flag: "-b", Arg: "{character}", Type: "string", Desc: "Blank character: default '.'."},
}

var BarSetup = TransformerSetup{
	Verb:         verbNameBar,
	UsageFunc:    transformerBarUsage,
	ParseCLIFunc: transformerBarParseCLI,
	IgnoresInput: false,
	Options:      barOptions,
}

func transformerBarUsage(
	o *os.File,
) {
	fmt.Fprintf(o, "Usage: %s %s [options]\n", "mlr", verbNameBar)
	fmt.Fprintf(o, "Replaces a numeric field with a number of asterisks, allowing for cheesy\n")
	fmt.Fprintf(o, "bar plots. These align best with --opprint or --oxtab output format.\n")
	WriteVerbOptions(o, barOptions)
	fmt.Fprintf(o, "Nominally the fill, out-of-bounds, and blank characters will be strings of length 1.\n")
	fmt.Fprintf(o, "However you can make them all longer if you so desire.\n")
}

func transformerBarParseCLI(
	pargi *int,
	argc int,
	args []string,
	_ *cli.TOptions,
	doConstruct bool, // false for first pass of CLI-parse, true for second pass
) (RecordTransformer, error) {

	// Skip the verb name from the current spot in the mlr command line
	argi := *pargi
	verb := args[argi]
	argi++

	// Parse local flags
	var err error
	var fieldNames []string = nil
	lo := barDefaultLo
	hi := barDefaultHi
	width := barDefaultWidth
	doAuto := false
	fillString := barDefaultFillString
	oobString := barDefaultOOBString
	blankString := barDefaultBlankString

	for argi < argc /* variable increment: 1 or 2 depending on flag */ {
		opt := args[argi]
		if !strings.HasPrefix(opt, "-") {
			break // No more flag options to process
		}
		if args[argi] == "--" {
			break // All transformers must do this so main-flags can follow verb-flags
		}
		argi++

		switch opt {
		case "-h", "--help":
			transformerBarUsage(os.Stdout)
			return nil, cli.ErrHelpRequested

		case "-f":
			fieldNames, err = cli.VerbGetStringArrayArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}

		case "--lo":
			lo, err = cli.VerbGetFloatArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}
		case "-w":
			width, err = cli.VerbGetIntArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}
		case "--hi":
			hi, err = cli.VerbGetFloatArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}

		case "-c":
			fillString, err = cli.VerbGetStringArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}
		case "-x":
			oobString, err = cli.VerbGetStringArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}
		case "-b":
			blankString, err = cli.VerbGetStringArg(verb, opt, args, &argi, argc)
			if err != nil {
				return nil, err
			}

		case "--auto":
			doAuto = true

		default:
			return nil, cli.VerbErrorf(verb, "option \"%s\" not recognized", opt)
		}
	}

	if fieldNames == nil {
		return nil, cli.VerbErrorf(verb, "-f field names required")
	}

	*pargi = argi
	if !doConstruct { // All transformers must do this for main command-line parsing
		return nil, nil
	}

	transformer, err := NewTransformerBar(
		fieldNames,
		lo,
		hi,
		int(width),
		doAuto,
		fillString,
		oobString,
		blankString,
	)
	if err != nil {
		return nil, err
	}

	return transformer, nil
}

type TransformerBar struct {
	fieldNames         []string
	lo                 float64
	hi                 float64
	width              int
	fillString         string
	oobString          string
	blankString        string
	bars               []string
	recordsForAutoMode []*types.RecordAndContext

	recordTransformerFunc RecordTransformerFunc
}

func NewTransformerBar(
	fieldNames []string,
	lo float64,
	hi float64,
	width int,
	doAuto bool,
	fillString string,
	oobString string,
	blankString string,
) (*TransformerBar, error) {

	tr := &TransformerBar{
		fieldNames:  fieldNames,
		lo:          lo,
		hi:          hi,
		width:       width,
		fillString:  fillString,
		oobString:   oobString,
		blankString: blankString,
	}

	tr.bars = make([]string, width+1)
	for i := 0; i <= tr.width; i++ {
		var bar string
		if i == 0 {
			bar = tr.oobString + strings.Repeat(tr.blankString, width-1)
		} else if i < width {
			bar = strings.Repeat(tr.fillString, i) + strings.Repeat(tr.blankString, width-i)
		} else {
			bar = strings.Repeat(tr.fillString, width-1) + tr.oobString
		}

		tr.bars[i] = bar
	}

	if doAuto {
		tr.recordTransformerFunc = tr.processAuto
		tr.recordsForAutoMode = []*types.RecordAndContext{}
	} else {
		tr.recordTransformerFunc = tr.processNoAuto
		tr.recordsForAutoMode = nil
	}

	return tr, nil
}

func (tr *TransformerBar) Transform(
	inrecAndContext *types.RecordAndContext,
	outputRecordsAndContexts *[]*types.RecordAndContext, // list of *types.RecordAndContext
	inputDownstreamDoneChannel <-chan bool,
	outputDownstreamDoneChannel chan<- bool,
) error {
	HandleDefaultDownstreamDone(inputDownstreamDoneChannel, outputDownstreamDoneChannel)
	return tr.recordTransformerFunc(inrecAndContext, outputRecordsAndContexts, inputDownstreamDoneChannel, outputDownstreamDoneChannel)
}

func (tr *TransformerBar) processNoAuto(
	inrecAndContext *types.RecordAndContext,
	outputRecordsAndContexts *[]*types.RecordAndContext, // list of *types.RecordAndContext
	inputDownstreamDoneChannel <-chan bool,
	outputDownstreamDoneChannel chan<- bool,
) error {
	if !inrecAndContext.EndOfStream {
		inrec := inrecAndContext.Record

		for _, fieldName := range tr.fieldNames {
			mvalue := inrec.Get(fieldName)
			if mvalue == nil {
				continue
			}
			floatValue, ok := mvalue.GetNumericToFloatValue()
			if !ok {
				continue
			}
			idx := min(max(int(float64(tr.width)*(floatValue-tr.lo)/(tr.hi-tr.lo)), 0), tr.width)
			inrec.PutReference(fieldName, mlrval.FromString(tr.bars[idx]))
		}

		*outputRecordsAndContexts = append(*outputRecordsAndContexts, inrecAndContext)
	} else {
		*outputRecordsAndContexts = append(*outputRecordsAndContexts, inrecAndContext) // emit end-of-stream marker
	}
	return nil
}

func (tr *TransformerBar) processAuto(
	inrecAndContext *types.RecordAndContext,
	outputRecordsAndContexts *[]*types.RecordAndContext, // list of *types.RecordAndContext
	inputDownstreamDoneChannel <-chan bool,
	outputDownstreamDoneChannel chan<- bool,
) error {
	if !inrecAndContext.EndOfStream {
		tr.recordsForAutoMode = append(tr.recordsForAutoMode, inrecAndContext.Copy())
		return nil
	}

	// Else, end of stream

	// Loop over field names to be barred
	for _, fieldName := range tr.fieldNames {
		lo := 0.0
		hi := 0.0

		// The first pass computes lo and hi from the data
		onFirst := true
		for _, recordAndContext := range tr.recordsForAutoMode {
			record := recordAndContext.Record
			mvalue := record.Get(fieldName)
			if mvalue == nil {
				continue
			}
			floatValue, ok := mvalue.GetNumericToFloatValue()
			if !ok {
				continue
			}

			if onFirst || floatValue < lo {
				lo = floatValue
			}
			if onFirst || floatValue > hi {
				hi = floatValue
			}
			onFirst = false
		}

		// The second pass applies the bars. There is some redundant computation
		// which could be hoisted out of the loop for performance ... but this
		// verb computes data solely for visual inspection and I take the
		// nominal use case to be tens or hundreds of records. So, optimization
		// isn't worth the effort here.

		slo := fmt.Sprintf("%g", lo)
		shi := fmt.Sprintf("%g", hi)

		for _, recordAndContext := range tr.recordsForAutoMode {
			record := recordAndContext.Record
			mvalue := record.Get(fieldName)
			if mvalue == nil {
				continue
			}
			floatValue, ok := mvalue.GetNumericToFloatValue()
			if !ok {
				continue
			}

			idx := min(max(int((float64(tr.width)*(floatValue-lo)/(hi-lo))), 0), tr.width)

			var buffer bytes.Buffer
			buffer.WriteString("[")
			buffer.WriteString(slo)
			buffer.WriteString("]")
			buffer.WriteString(tr.bars[idx])
			buffer.WriteString("[")
			buffer.WriteString(shi)
			buffer.WriteString("]")
			record.PutReference(fieldName, mlrval.FromString(buffer.String()))
		}
	}

	*outputRecordsAndContexts = append(*outputRecordsAndContexts, tr.recordsForAutoMode...)

	*outputRecordsAndContexts = append(*outputRecordsAndContexts, inrecAndContext) // Emit the end-of-stream marker
	return nil
}