check

package
v2.1.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 18, 2023 License: MIT Imports: 11 Imported by: 31

Documentation

Overview

Package check provides a collection of atomic checks that can be applied to values.

Each of the check functions returns an error if the value doesn't pass the check or nil if the check is passed. For instance a function of type check.X will typically take a variable of type X and return an error if the value does not pass the check. Where a check is parameterised there is typically a function which returns a check function as a closure.

The checks are typically very simple to the point where you might question why not perform the check directly. The reason is that as functions they can be composed and combined and then passed to other code to be called later. They are used extensively for checking command line parameters.

Many of the types have a ...Not function that can be used to invert the meaning of a check. Similarly, there are ...And and ...Or functions which can be used to compose checks.

Example

Example demonstrates how check functions might be used. It sets up two collections of checks on a slice of strings, the first collection should all pass (return a nil error) and the second set should all fail. Note that the check functions called below each returns a function of type check.StringSlice. For instance check.SliceLength(check.ValEQ(2)) returns a check.StringSlice function that will check that the given slice is of length 2. This technique is used throughout the package. 

package main

import (
	"fmt"

	"github.com/nickwells/check.mod/v2/check"
)

func main() {
	s := []string{"hello", "world"}

	passingChecks := []check.ValCk[[]string]{
		check.SliceLength[[]string](check.ValEQ(2)),
		check.SliceAny[[]string](
			check.ValEQ("hello"),
			"the list of strings must contain 'hello'"),
	}

	for _, c := range passingChecks {
		if err := c(s); err != nil {
			fmt.Println("unexpected error: ", err)
			return
		}
	}
	fmt.Println("All checks expected to pass, passed")

	failingChecks := []check.ValCk[[]string]{
		check.SliceLength[[]string](check.ValEQ(3)),
		check.Not(
			check.SliceHasNoDups[[]string],
			"the list of strings must contain duplicates"),
	}

	var someCheckPassed bool
	for i, c := range failingChecks {
		if err := c(s); err == nil {
			fmt.Println("unexpected check success: ", i)
			someCheckPassed = true
		}
	}
	if !someCheckPassed {
		fmt.Println("All checks expected to fail, failed")
	}

}

Output:

All checks expected to pass, passed
All checks expected to fail, failed

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FileInfoIsDir 

func FileInfoIsDir(fi fs.FileInfo) error

FileInfoIsDir will check that the file info describes a directory

func FileInfoIsRegular 

func FileInfoIsRegular(fi fs.FileInfo) error

FileInfoIsRegular will check that the file info describes a regular file

func FileInfoOwnedBySelf 

func FileInfoOwnedBySelf(fi fs.FileInfo) error

FileInfoOwnedBySelf tests that the file is owned by the calling user

func SliceHasNoDups 

func SliceHasNoDups[S ~[]E, E comparable](v S) error

SliceHasNoDups checks that the list contains no duplicates

func TimeIsALeapYear added in v2.1.0 

func TimeIsALeapYear(t time.Time) error

TimeIsALeapYear checks that the time value falls on a leap year

func ValOK 

func ValOK[T any](_ T) error

ValOK always returns a nil error - it can be of use with a check.ByPos to allow any value in certain slice positions

Types

type Aggregator 

type Aggregator[T any] interface {
	Aggregate(val T) error
	Test() error
}

Aggregator is the type of an interface offering an Aggregate function and a Test function. The expectation is that the Aggregate function will be called over a range of values and will produce some kind of aggregate value which will be tested later with the test function.

type Counter 

type Counter[T any] struct {
	// contains filtered or unexported fields
}

Counter implements the Aggregator interface. It counts the values that pass the the value test and applies the count test

func NewCounter 

func NewCounter[T any](valueTest ValCk[T], countTest ValCk[int]) *Counter[T]

NewCounter returns an instance of a Counter with the valueTest and countTest functions set from the parameters. If either test is nil a panic is generated.

func (*Counter[T]) Aggregate 

func (c *Counter[T]) Aggregate(val T) error

Aggregate counts the number of values that pass the valueTest

func (Counter[T]) Test 

func (c Counter[T]) Test() error

Test applies the testFunc to the count

type Duration added in v2.0.1 

type Duration = ValCk[time.Duration]

These aliases are to simplify the migration to the v2.0.0 version

type FileInfo added in v2.0.1 

type FileInfo = ValCk[fs.FileInfo]

These aliases are to simplify the migration to the v2.0.0 version

type FilePerm added in v2.0.1 

type FilePerm = ValCk[fs.FileMode]

These aliases are to simplify the migration to the v2.0.0 version

type Float64 added in v2.0.1 

type Float64 = ValCk[float64]

These aliases are to simplify the migration to the v2.0.0 version

type Int64 added in v2.0.1 

type Int64 = ValCk[int64]

These aliases are to simplify the migration to the v2.0.0 version

type Int64Slice added in v2.0.1 

type Int64Slice = ValCk[[]int64]

These aliases are to simplify the migration to the v2.0.0 version

type MapStringBool added in v2.0.1 

type MapStringBool = ValCk[map[string]bool]

These aliases are to simplify the migration to the v2.0.0 version

type String added in v2.0.1 

type String = ValCk[string]

These aliases are to simplify the migration to the v2.0.0 version

type StringSlice added in v2.0.1 

type StringSlice = ValCk[[]string]

These aliases are to simplify the migration to the v2.0.0 version

type Time added in v2.0.1 

type Time = ValCk[time.Time]

These aliases are to simplify the migration to the v2.0.0 version

type TimeLocation added in v2.0.1 

type TimeLocation = ValCk[time.Location]

These aliases are to simplify the migration to the v2.0.0 version

type ValCk 

type ValCk[T any] func(v T) error

ValCk is the type of a check function

func And 

func And[T any](chkFuncs ...ValCk[T]) ValCk[T]

And returns a function that will check that the value, when passed to each of the check funcs in turn, passes all of them. The error from the first check to fail is returned.

func FileInfoGidEQ 

func FileInfoGidEQ(gid uint32) ValCk[fs.FileInfo]

FileInfoGidEQ returns a function that tests that the file is owned by the specified user

func FileInfoModTime 

func FileInfoModTime(cf ValCk[time.Time]) ValCk[fs.FileInfo]

FileInfoModTime returns a function that will check that the file modification time passes the test specified by the passed Time check

func FileInfoMode 

func FileInfoMode(m fs.FileMode) ValCk[fs.FileInfo]

FileInfoMode returns a function that will check that the file mode type matches the value passed. Typically this will be a single value as enumerated in the os package under FileMode but if more than one value is given (and'ed together as a bitmask) then if any of the bits is set this function will return nil if any of the bits is set. This allows you to check for several types at once. If a zero value is passed it will check for a regular file - none of the bits are set.

func FileInfoName 

func FileInfoName(cf ValCk[string]) ValCk[fs.FileInfo]

FileInfoName returns a function that will check that the file name passes the test specified by the passed String check

func FileInfoPerm 

func FileInfoPerm(cf ValCk[fs.FileMode]) ValCk[fs.FileInfo]

FileInfoPerm returns a function that will check that the file permissions pass the test specified by the passed FilePerm check

func FileInfoSize 

func FileInfoSize(cf ValCk[int64]) ValCk[fs.FileInfo]

FileInfoSize returns a function that will check that the file size passes the test specified by the passed Int64 check

func FileInfoUidEQ 

func FileInfoUidEQ(uid uint32) ValCk[fs.FileInfo]

FileInfoUidEQ returns a function that tests that the file is owned by the specified user

func FilePermEQ 

func FilePermEQ(perms fs.FileMode) ValCk[fs.FileMode]

FilePermEQ returns a function that will check that the file permission is set to the value of the perms parameter

func FilePermHasAll 

func FilePermHasAll(perms fs.FileMode) ValCk[fs.FileMode]

FilePermHasAll returns a function that will check that the file permission has all of the permissions set in the perms parameter

func FilePermHasNone 

func FilePermHasNone(perms fs.FileMode) ValCk[fs.FileMode]

FilePermHasNone returns a function that will check that the file permission has none of the permissions set in the perms parameter

func MapKeyAggregate 

func MapKeyAggregate[M ~map[K]V, K comparable, V any](a Aggregator[K]) ValCk[M]

MapKeyAggregate returns a function that will apply the Aggregate method of the suplied Aggregator to the keys in the map and will then return the results of the Test func.

Note that if any of the calls to Aggregate returns a non-nil error the aggregation will stop and the error will be returned without the Test function being called.

func MapKeyAll 

func MapKeyAll[M ~map[K]V, K comparable, V any](cf ValCk[K]) ValCk[M]

MapKeyAll returns a function that will apply the supplied check function to each key in the map and will return an error for the first key for which it fails.

It returns nil if all the keys pass the supplied check

func MapKeyAny 

func MapKeyAny[M ~map[K]V, K comparable, V any](cf ValCk[K], msg string) ValCk[M]

MapKeyAny returns a function that will apply the supplied check function to each key in the map and will return an error if all of them fail the test. The msg parameter should describe the check being performed. For instance, for a map keyed with strings, if the check is that the string length must be greater than 5 characters then the condition parameter should be: 

"the string should be greater than 5 characters"

It returns nil if any of the keys pass the supplied check

func MapLength 

func MapLength[M ~map[K]V, K comparable, V any](cf ValCk[int]) ValCk[M]

MapLength returns a function that will apply the supplied check func to the length of a supplied value and return an error if the check function returns an error

func MapValAggregate 

func MapValAggregate[M ~map[K]V, K comparable, V any](a Aggregator[V]) ValCk[M]

MapValAggregate returns a function that will apply the Aggregate method of the suplied Aggregator to the values in the map and will then return the results of the Test func.

Note that if any of the calls to Aggregate returns a non-nil error the aggregation will stop and the error will be returned without the Test function being called.

func MapValAll 

func MapValAll[M ~map[K]V, K comparable, V any](cf ValCk[V]) ValCk[M]

MapValAll returns a function that will apply the supplied check function to each value in the map and will return an error for the first value for which it fails.

It returns nil if all the values pass the supplied check

func MapValAny 

func MapValAny[M ~map[K]V, K comparable, V any](cf ValCk[V], msg string) ValCk[M]

MapValAny returns a function that will apply the supplied check function to each value in the map and will return an error if all of them fail the test. The msg parameter should describe the check being performed. For instance, for a map keyed with strings, if the check is that the string length must be greater than 5 characters then the condition parameter should be: 

"the string should be greater than 5 characters"

It returns nil if any of the values pass the supplied check

func Not 

func Not[T any](c ValCk[T], errMsg string) ValCk[T]

Not returns a function that will check that the value, when passed to the check func, does not pass it. You must also supply the error text to appear after the value that fails. This error text should be a string that describes the quality that the number should not have. So, for instance, if the function being Not'ed was 

check.ValGT[T any](5)

then the errMsg parameter should be 

"a number greater than 5".

func Or 

func Or[T any](chkFuncs ...ValCk[T]) ValCk[T]

Or returns a function that will check that the value, when passed to each of the check funcs in turn, passes at least one of them. If any check passes a nil error is returned. The error returned (if any) will show all the failing checks.

func SliceAggregate 

func SliceAggregate[S ~[]E, E any](a Aggregator[E]) ValCk[S]

SliceAggregate returns a function that will apply the Aggregate method of the suplied Aggregator to the values in the slice and will then return the results of the Test func.

Note that if any of the calls to Aggregate returns a non-nil error the aggregation will stop and the error will be returned without the Test function being called.

func SliceAll 

func SliceAll[S ~[]E, E any](cf ValCk[E]) ValCk[S]

SliceAll returns a function that will apply the supplied check func to each of the elements of the slice in turn and if any one of them fails the test it's location (index) in the slice and the error will be returned as an error.

It returns nil if all the entries pass the check.

func SliceAny 

func SliceAny[S ~[]E, E any](cf ValCk[E], msg string) ValCk[S]

SliceAny returns a function that will apply the supplied check func to each of the elements of the slice in turn and if all of them fail the test it returns an error. The msg parameter should describe the check being performed. For instance, for a slice of strings, if the check is that the string length must be greater than 5 characters then the condition parameter should be: 

"the string should be greater than 5 characters"

It returns nil if any of the entries pass the supplied check.

func SliceByPos 

func SliceByPos[S ~[]E, E any](cfs ...ValCk[E]) ValCk[S]

SliceByPos returns a check function that checks that a given entry in the slice passes the corresponding supplied check func. If there are more entries in the slice than check functions then the final supplied check is applied to any remaining entries. If there are fewer entries than functions then the excess checks are not applied. Note that you could choose to combine this check with a ValLength by means of a ValCkAnd check.

func SliceLength 

func SliceLength[S ~[]E, E any](cf ValCk[int]) ValCk[S]

SliceLength returns a function that will apply the supplied check func to the length of a supplied value and return an error if the check function returns an error

func StringContains added in v2.1.0 

func StringContains[T ~string](substr string) ValCk[T]

StringContains returns a function that checks that the string contains the supplied string

func StringFoldedEQ added in v2.1.0 

func StringFoldedEQ[T ~string](s string) ValCk[T]

StringFoldedEQ returns a function that checks that the string is equal to the supplied string under Unicode case-folding.

func StringHasPrefix 

func StringHasPrefix[T ~string](prefix string) ValCk[T]

StringHasPrefix returns a function that checks that the string has the supplied string as a prefix

func StringHasSuffix 

func StringHasSuffix[T ~string](suffix string) ValCk[T]

StringHasSuffix returns a function that checks that the string has the supplied string as a suffix

func StringLength 

func StringLength[T ~string](cf ValCk[int]) ValCk[T]

StringLength returns a function that will apply the supplied check func to the length of a supplied value and return an error if the check function returns an error

func StringMatchesPattern 

func StringMatchesPattern[T ~string](re *regexp.Regexp, reDesc string) ValCk[T]

StringMatchesPattern returns a function that checks that the string matches the supplied regexp. The regexp description should be a description of the string that will match the regexp. The error returned will say that the string "should be: " followed by this description. So, for instance, if the regexp matches a string of numbers then the description could be 'numeric'.

func TimeBetween 

func TimeBetween(start, end time.Time) ValCk[time.Time]

TimeBetween returns a function that will check that the tested time is between the start and end times (inclusive)

func TimeEQ 

func TimeEQ(t time.Time) ValCk[time.Time]

TimeEQ returns a function that will check that the tested time is equal to the time.Time parameters

func TimeGE 

func TimeGE(t time.Time) ValCk[time.Time]

TimeGE returns a function that will check that the tested time is after or equal to the time.Time parameter

func TimeGT 

func TimeGT(t time.Time) ValCk[time.Time]

TimeGT returns a function that will check that the tested time is after the time.Time parameter

func TimeIsNthWeekdayOfMonth added in v2.1.0 

func TimeIsNthWeekdayOfMonth(n int, dow time.Weekday) ValCk[time.Time]

TimeIsNthWeekdayOfMonth returns a function that will check that the time is on the nth day of the week of the month. Negative values for n mean that the check is from the end of the month.

func TimeIsOnDOW 

func TimeIsOnDOW(dow time.Weekday, otherDOW ...time.Weekday) ValCk[time.Time]

TimeIsOnDOW returns a function that will check that the time is on the day of the week given by one of the parameters

func TimeLE 

func TimeLE(t time.Time) ValCk[time.Time]

TimeLE returns a function that will check that the tested time is before or equal to the time.Time parameter

func TimeLT 

func TimeLT(t time.Time) ValCk[time.Time]

TimeLT returns a function that will check that the tested time is before the time.Time parameter

func TimeNE 

func TimeNE(t time.Time) ValCk[time.Time]

TimeNE returns a function that will check that the tested time is not equal to the time.Time parameters

func ValBetween 

func ValBetween[T constraints.Ordered](low, high T) ValCk[T]

ValBetween returns a function that will check that the value lies between the upper and lower limits (inclusive)

func ValDivides 

func ValDivides[T constraints.Integer](d T) ValCk[T]

ValDivides returns a function that will check that the value is a divisor of d

func ValEQ 

func ValEQ[T comparable](limit T) ValCk[T]

ValEQ returns a function that will check that the value is equal to the limit

func ValGE 

func ValGE[T constraints.Ordered](limit T) ValCk[T]

ValGE returns a function that will check that the value is greater than or equal to the limit

func ValGT 

func ValGT[T constraints.Ordered](limit T) ValCk[T]

ValGT returns a function that will check that the value is greater than the limit

func ValIsAMultiple 

func ValIsAMultiple[T constraints.Integer](d T) ValCk[T]

ValIsAMultiple returns a function that will check that the value is a multiple of d

func ValLE 

func ValLE[T constraints.Ordered](limit T) ValCk[T]

ValLE returns a function that will check that the value is less than or equal to the limit

func ValLT 

func ValLT[T constraints.Ordered](limit T) ValCk[T]

ValLT returns a function that will check that the value is less than the limit

func ValNE 

func ValNE[T comparable](limit T) ValCk[T]

ValNE returns a function that will check that the value is not equal to the limit

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.