Filtering docs and tests

Author: jotaen

klog/app/cli/args/filter.go

@@ -11,10 +11,10 @@ import (
 
 type FilterArgs struct {
 	// Date-related filters:
-	Date   klog.Date     `name:"date" placeholder:"DATE" group:"Filter Flags:" help:"Entries at this date. DATE has to be in format YYYY-MM-DD or YYYY/MM/DD. E.g., '2024-01-31' or '2024/01/31'."`
-	Since  klog.Date     `name:"since" placeholder:"DATE" group:"Filter Flags:" help:"Entries since this date (inclusive)."`
-	Until  klog.Date     `name:"until" placeholder:"DATE" group:"Filter Flags:" help:"Entries until this date (inclusive)."`
-	Period period.Period `name:"period" placeholder:"PERIOD" group:"Filter Flags:" help:"Entries within a calendar period. PERIOD has to be in format YYYY, YYYY-MM, YYYY-Www or YYYY-Qq. E.g., '2024', '2024-04', '2022-W21' or '2024-Q1'."`
+	Date   klog.Date     `name:"date" placeholder:"DATE" group:"Filter Flags:" help:"Records at this date. DATE has to be in format YYYY-MM-DD or YYYY/MM/DD. E.g., '2024-01-31' or '2024/01/31'."`
+	Since  klog.Date     `name:"since" placeholder:"DATE" group:"Filter Flags:" help:"Records since this date (inclusive)."`
+	Until  klog.Date     `name:"until" placeholder:"DATE" group:"Filter Flags:" help:"Records until this date (inclusive)."`
+	Period period.Period `name:"period" placeholder:"PERIOD" group:"Filter Flags:" help:"Records within a calendar period. PERIOD has to be in format YYYY, YYYY-MM, YYYY-Www or YYYY-Qq. E.g., '2024', '2024-04', '2022-W21' or '2024-Q1'."`
 
 	// Filter shortcuts:
 	// The two `XXX` ones are dummy entries just for the help output, they also aren’t available
@@ -34,8 +34,8 @@ type FilterArgs struct {
 	LastYear    bool `hidden:"" name:"last-year" group:"Filter Flags:" completion-enabled:"true"`
 
 	// General filters:
-	Tags   []klog.Tag `name:"tag" placeholder:"TAG" group:"Filter Flags:" help:"Entries that match these tags (either in the record summary or the entry summary). You can omit the leading '#'."`
-	Filter string     `name:"filter" placeholder:"EXPR" group:"Filter Flags:" help:"Entries that match this filter expression. Run 'klog info --filtering' to learn how expressions works."`
+	Tags   []klog.Tag `name:"tag" placeholder:"TAG" group:"Filter Flags:" help:"Records or entries that match these tags (either in the record summary or the entry summary). You can omit the leading '#'."`
+	Filter string     `name:"filter" placeholder:"EXPR" group:"Filter Flags:" help:"Records or entries that match this filter expression. Run 'klog info --filtering' to learn how expressions works."`
 
 	hasPartialRecordsWithShouldTotal bool          // Field only for internal use
 	singleShortHandFilter            period.Period // Field only for internal use
@@ -140,7 +140,7 @@ func (args *FilterArgs) ApplyFilter(now gotime.Time, rs []klog.Record) ([]klog.R
 }
 
 // SinglePeriodRequested returns the corresponding period if a single short-hand
-// filter (such as --this-month or --last-week) was used.
+// periodic filter (such as --this-month, --period) was used.
 func (args *FilterArgs) SinglePeriodRequested() period.Period {
 	return args.singleShortHandFilter
 }

klog/app/cli/args/misc.go

@@ -18,7 +18,7 @@ type DiffArgs struct {
 // nonsensical results.
 func (args *DiffArgs) GetWarning(filterArgs FilterArgs) service.UsageWarning {
 	if args.Diff && filterArgs.hasPartialRecordsWithShouldTotal {
-		return service.DiffEntryFilteringWarning
+		return service.EntryFilteredDiffWarning
 	}
 	return service.UsageWarning{}
 }

klog/app/cli/info.go

@@ -25,7 +25,9 @@ func (opt *Info) Run(ctx app.Context) app.Error {
 
     klog total --filter='2025-04 && #work' mytimes.klg
 
-This would evaluate all entries in April 2025 that match the tag #work. Wrap the filter expression in single quotes to avoid undesired shell word splitting or substitution. Filter expressions consist of operands for matching the data that shall be included in the filter result. Operands can be combined via logical operators and grouped via parentheses.
+This would evaluate all records and entries in April 2025 that match the tag #work. Wrap the filter expression in single quotes to avoid undesired shell word splitting or substitution. Filter expressions consist of operands for matching the data that shall be included in the filter result. Operands can be combined via logical operators and grouped via parentheses.
+
+Filters can match at record-level and/or at entry-level. It only keeps the data that satisfies the filter condition. For entry-level filters, this means that all non-matching entries are stripped from the record.
 
 Examples:
     2025-04-20 || 2020-04-21

klog/app/cli/print.go

@@ -25,8 +25,6 @@ func (opt *Print) Help() string {
 Outputs data on the terminal, by default with syntax-highlighting turned on.
 Note that the output doesn’t resemble the file verbatim, but it may apply some minor formatting.
 
-If run with filter flags, it only outputs those entries that match the filter clauses. E.g., when filtering for a tag that only appears particular entries, it will exclude all other entries from that record.
-
 You can optionally also sort the records, or print out the total times for each record and entry.
 `
 }

klog/service/filter/filter_test.go

@@ -74,6 +74,24 @@ func TestQueryWithNoClauses(t *testing.T) {
 	}, rs)
 }
 
+func TestQueryWithNoMatches(t *testing.T) {
+	rs, hprws := Filter(IsInDateRange{
+		From: klog.Ɀ_Date_(2002, 1, 1),
+		To:   klog.Ɀ_Date_(2002, 1, 1),
+	}, sampleRecordsForQuerying())
+	assert.False(t, hprws)
+	assertResult(t, []expect{}, rs)
+}
+
+func TestQueryAgainstEmptyInput(t *testing.T) {
+	rs, hprws := Filter(IsInDateRange{
+		From: klog.Ɀ_Date_(2002, 1, 1),
+		To:   klog.Ɀ_Date_(2002, 1, 1),
+	}, nil)
+	assert.False(t, hprws)
+	assertResult(t, []expect{}, rs)
+}
+
 func TestQueryWithAtDate(t *testing.T) {
 	rs, hprws := Filter(IsInDateRange{
 		From: klog.Ɀ_Date_(2000, 1, 2),
@@ -239,4 +257,19 @@ func TestComplexFilterQueries(t *testing.T) {
 			{klog.Ɀ_Date_(2000, 1, 3), []int{240}},
 		}, rs)
 	}
+	{
+		rs, hprws := Filter(Not{Or{[]Predicate{
+			IsInDateRange{From: klog.Ɀ_Date_(1999, 12, 30), To: klog.Ɀ_Date_(2000, 1, 1)},
+			HasTag{klog.NewTagOrPanic("xyz", "")},
+			And{[]Predicate{
+				IsEntryType{ENTRY_TYPE_DURATION_POSITIVE},
+				HasTag{klog.NewTagOrPanic("bar", "")},
+			}},
+		}}}, sampleRecordsForQuerying())
+		assert.True(t, hprws)
+		assertResult(t, []expect{
+			{klog.Ɀ_Date_(1999, 12, 29), []int{}},
+			{klog.Ɀ_Date_(2000, 1, 3), []int{240, 0}},
+		}, rs)
+	}
 }

klog/service/filter/predicate.go

@@ -7,7 +7,8 @@ import (
 	"github.com/jotaen/klog/klog"
 )
 
-// Predicate is the generic base type for all predicates.
+// Predicate is the generic base type for all predicates. The caller is responsible for
+// selecting the applicable match function (it’s meant to be either/or).
 type Predicate interface {
 	// Matches returns true if the record’s entry satisfies the predicate.
 	Matches(klog.Record, klog.Entry) bool

klog/service/warning.go

@@ -18,7 +18,7 @@ var (
 		Name:    "POINTLESS_NOW",
 		Message: "You specified --now, but there was no open-ended time range",
 	}
-	DiffEntryFilteringWarning = UsageWarning{
+	EntryFilteredDiffWarning = UsageWarning{
 		Name:    "ENTRY_FILTERED_DIFFING",
 		Message: "Combining --diff and filtering at entry-level may yield nonsensical results",
 	}
@@ -41,7 +41,7 @@ func NewDisabledCheckers() DisabledCheckers {
 		(&overlappingTimeRangesChecker{}).Name(): false,
 		(&moreThan24HoursChecker{}).Name():       false,
 		PointlessNowWarning.Name:                 false,
-		DiffEntryFilteringWarning.Name:           false,
+		EntryFilteredDiffWarning.Name:            false,
 	}
 }