Optionally include bar chart renderings for klog report

Related #336.

This PR adds a `--chart` (`-c`) flag to the `klog report` command, which
includes bar chart diagrams in the output like so:

```
$ klog report --chart worktimes.klg

                       Total                                  
2025 Jan    Tue 14.       6h  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇        
            Thu 16.    7h30m  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇  
            Fri 17.    6h45m  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇     
            Sat 18.       8h  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
            Mon 20.    3h20m  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇                  
            Wed 22.    7h45m  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 
            Sat 25.    7h15m  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇   
                    ========                                  
                      46h35m                                  
```

The default resolution of the bars depends on the aggregation mode.
(Remember: aggregation defaults to daily, unless specified via
`--aggregate`/`-a`). The default resolution aims to make for a good
balance between granularity and row width for typical usage scenarios
(e.g., tracking work times). The resolution can be overridden with the
`--chart-res` flag; it needs to be a positive integer, denoting the
number of minutes per rendered block.

One implementation note for reference: I originally tried to use
Unicode’s [“eighths” type block
characters](https://www.compart.com/en/unicode/block/U+2580) to make the
bars more precise. This didn’t work out so well, however, because on
some systems, the full block and the “eighths” blocks render at a
slightly different height, which looks weird.

Author: jotaen

CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 **Summary of changes of the command line tool**
 
+## Scheduled for next release
+- **[ FEATURE ]** Add `--chart` flag to `klog report` command, which
+  includes bar chart renderings in the output, to allow for convenient visual
+  comparison at a glance. (See also `--chart-resolution`.)
+
 ## v6.5 (2024-11-28)
 - **[ FEATURE ]** Introduce `basic` colour scheme based on the basic 8-bit ANSI
   colours – see `colour_scheme` entry in `config.ini` file. (Run `klog config` to

klog/app/cli/report.go

@@ -8,12 +8,15 @@ import (
 	"github.com/jotaen/klog/klog/app/cli/util"
 	"github.com/jotaen/klog/klog/service"
 	"github.com/jotaen/klog/klog/service/period"
+	"math"
 	"strings"
 )
 
 type Report struct {
-	AggregateBy string `name:"aggregate" placeholder:"KIND" short:"a" help:"How to aggregate the data. KIND can be 'day' (default), 'week', 'month', 'quarter' or 'year'." enum:"DAY,day,d,WEEK,week,w,MONTH,month,m,QUARTER,quarter,q,YEAR,year,y," default:"day"`
-	Fill        bool   `name:"fill" short:"f" help:"Fill the gaps and show a consecutive stream."`
+	AggregateBy     string `name:"aggregate" placeholder:"KIND" short:"a" help:"How to aggregate the data. KIND can be 'day' (default), 'week', 'month', 'quarter' or 'year'." enum:"DAY,day,d,WEEK,week,w,MONTH,month,m,QUARTER,quarter,q,YEAR,year,y," default:"day"`
+	Fill            bool   `name:"fill" short:"f" help:"Fill any calendar gaps and show a consecutive sequence of dates."`
+	Chart           bool   `name:"chart" short:"c" help:"Includes a bar chart rendering, to aid visual comparison."`
+	ChartResolution int    `name:"chart-res" help:"Configure the chart resolution. INT must be a positive integer, denoting the minutes per rendered block."`
 	util.DiffArgs
 	util.FilterArgs
 	util.NowArgs
@@ -36,6 +39,10 @@ If you want a consecutive, chronological stream, you can use the '--fill' flag.
 func (opt *Report) Run(ctx app.Context) app.Error {
 	opt.DecimalArgs.Apply(&ctx)
 	opt.NoStyleArgs.Apply(&ctx)
+	cErr := opt.canonicaliseOpts()
+	if cErr != nil {
+		return cErr
+	}
 	_, serialiser := ctx.Serialise()
 	records, err := ctx.ReadInputs(opt.File...)
 	if err != nil {
@@ -51,18 +58,22 @@ func (opt *Report) Run(ctx app.Context) app.Error {
 		return nErr
 	}
 	records = service.Sort(records, true)
-	aggregator := opt.findAggregator()
+	aggregator := opt.aggregator()
 	recordGroups, dates := groupByDate(aggregator.DateHash, records)
 	if opt.Fill {
 		dates = allDatesRange(records[0].Date(), records[len(records)-1].Date())
 	}
 
 	// Table setup
 	numberOfValueColumns := func() int {
+		n := 1
 		if opt.Diff {
-			return 3
+			n += 2
+		}
+		if opt.Chart {
+			n += 1
 		}
-		return 1
+		return n
 	}()
 	table := tf.NewTable(
 		aggregator.NumberOfPrefixColumns()+numberOfValueColumns,
@@ -75,6 +86,9 @@ func (opt *Report) Run(ctx app.Context) app.Error {
 	if opt.Diff {
 		table.CellR("   Should").CellR("    Diff")
 	}
+	if opt.Chart {
+		table.Skip(1)
+	}
 
 	// Rows
 	hashesAlreadyProcessed := make(map[period.Hash]bool)
@@ -99,38 +113,73 @@ func (opt *Report) Run(ctx app.Context) app.Error {
 			diff := service.Diff(should, total)
 			table.CellR(serialiser.ShouldTotal(should)).CellR(serialiser.SignedDuration(diff))
 		}
+		if opt.Chart {
+			table.CellL(" " + renderBar(opt.ChartResolution, total))
+		}
 	}
 
 	// Line
 	table.Skip(aggregator.NumberOfPrefixColumns()).Fill("=")
 	if opt.Diff {
 		table.Fill("=").Fill("=")
 	}
-	grandTotal := service.Total(records...)
+	if opt.Chart {
+		table.Skip(1)
+	}
 
 	// Footer
+	grandTotal := service.Total(records...)
 	table.Skip(aggregator.NumberOfPrefixColumns())
 	table.CellR(serialiser.Duration(grandTotal))
 	if opt.Diff {
 		grandShould := service.ShouldTotalSum(records...)
 		grandDiff := service.Diff(grandShould, grandTotal)
 		table.CellR(serialiser.ShouldTotal(grandShould)).CellR(serialiser.SignedDuration(grandDiff))
 	}
+	if opt.Chart {
+		table.Skip(1)
+	}
 
 	table.Collect(ctx.Print)
 	opt.WarnArgs.PrintWarnings(ctx, records, opt.GetNowWarnings())
 	return nil
 }
 
-func (opt *Report) findAggregator() report.Aggregator {
-	category := (func() string {
-		if opt.AggregateBy == "" {
-			return "d"
-		} else {
-			return strings.ToLower(opt.AggregateBy[:1])
+func (opt *Report) canonicaliseOpts() app.Error {
+	if opt.AggregateBy == "" {
+		opt.AggregateBy = "d"
+	} else {
+		opt.AggregateBy = strings.ToLower(opt.AggregateBy[:1])
+	}
+
+	if opt.ChartResolution == 0 {
+		// If the resolution wasn’t explicitly specified, use a default value
+		// that aims for a good balance between granularity and overall row width
+		// in the context of the desired aggregation mode.
+		switch opt.AggregateBy {
+		case "y":
+			opt.ChartResolution = 60 * 8 * 7 // Full working week
+		case "q":
+			opt.ChartResolution = 60 * 8 // Full working day
+		case "m":
+			opt.ChartResolution = 60 * 4 // Half working day
+		case "w":
+			opt.ChartResolution = 60
+		default: // "d"
+			opt.ChartResolution = 15
 		}
-	})()
-	switch category {
+	} else if opt.ChartResolution > 0 {
+		// When chart resolution is specified, automatically assume --chart
+		// to be given as well.
+		opt.Chart = true
+	} else if opt.ChartResolution < 0 {
+		return app.NewErrorWithCode(app.LOGICAL_ERROR, "Invalid resolution", "The resolution must be a positive integer", nil)
+	}
+	return nil
+}
+
+func (opt *Report) aggregator() report.Aggregator {
+	switch opt.AggregateBy {
 	case "y":
 		return report.NewYearAggregator()
 	case "q":
@@ -169,3 +218,15 @@ func groupByDate(hashProvider func(klog.Date) period.Hash, rs []klog.Record) (ma
 	}
 	return days, order
 }
+
+func renderBar(minutesPerUnit int, d klog.Duration) string {
+	block := "▇"
+	blocksCount := func() int {
+		mins := d.InMinutes()
+		if mins <= 0 {
+			return 0
+		}
+		return int(math.Ceil(float64(mins) / float64(minutesPerUnit)))
+	}()
+	return strings.Repeat(block, blocksCount)
+}