Skip to content

Latest commit

 

History

History
1305 lines (899 loc) · 27.3 KB

README.md

File metadata and controls

1305 lines (899 loc) · 27.3 KB
Raw

GoDoc License Go Report Card Go CI codecov

Checker

Checker is a Go library that helps you validate user input. It can be used to validate user input stored in a struct, or to validate individual pieces of input.

There are many validation libraries available, but I prefer to build my own tools and avoid pulling in unnecessary dependencies. That's why I created Checker, a simple validation library with no dependencies. It's easy to use and gets the job done.

Usage

To get started, install the Checker library with the following command:

go get github.com/cinar/checker

Next, you will need to import the library into your source file. You can do this by following the example below:

import (
    "github.com/cinar/checker"
)

Validating User Input Stored in a Struct

Checker can be used in two ways. The first way is to validate user input stored in a struct. To do this, you can list the checkers through the struct tag for each field. Here is an example:

type Person struct {
    Name string `checkers:"required"`
}

person := &Person{}

errors, valid := checker.Check(person)
if !valid {
    // Send the errors back to the user
}

Validating Individual User Input

If you do not want to validate user input stored in a struct, you can individually call the checker functions to validate the user input. Here is an example:

var name

err := checker.IsRequired(name)
if err != nil {
    // Send the result back to the user
}

Normalizers and Checkers

Checkers are used to check for problems in user input, while normalizers are used to transform user input into a preferred format. For example, a normalizer could be used to trim spaces from the beginning and end of a string, or to convert a string to title case.

I am not entirely happy with the decision to combine checkers and normalizers into a single library, but using them together can be useful. Normalizers and checkers can be mixed in any order when defining the validation steps for user data. For example, the trim normalizer can be used in conjunction with the required checker to first trim the user input and then check if the user provided the required information. Here is an example:

type Person struct {
    Name string `checkers:"trim required"`
}

Checkers Provided

This package currently provides the following checkers:

  • alphanumeric checks if the given string consists of only alphanumeric characters.
  • ascii checks if the given string consists of only ASCII characters.
  • cidr checker checks if the value is a valid CIDR notation IP address and prefix length.
  • credit-card checks if the given value is a valid credit card number.
  • digits checks if the given string consists of only digit characters.
  • email checks if the given string is an email address.
  • fqdn checks if the given string is a fully qualified domain name.
  • ip checks if the given value is an IP address.
  • ipv4 checks if the given value is an IPv4 address.
  • ipv6 checks if the given value is an IPv6 address.
  • isbn checks if the given value is a valid ISBN number.
  • luhn checks if the given number is valid based on the Luhn algorithm.
  • mac checks if the given value is a valid an IEEE 802 MAC-48, EUI-48, EUI-64, or a 20-octet IP over InfiniBand link-layer address.
  • max checks if the given value is less than the given maximum.
  • max-length checks if the length of the given value is less than the given maximum length.
  • min checks if the given value is greather than the given minimum.
  • min-length checks if the length of the given value is greather than the given minimum length.
  • regexp checks if the given string matches the regexp pattern.
  • required checks if the required value is provided.
  • same checks if the given value is equal to the value of the field with the given name.
  • url checks if the given value is a valid URL.

Normalizers Provided

This package currently provides the following normalizers. They can be mixed with the checkers when defining the validation steps for user data.

  • html-escape applies HTML escaping to special characters.
  • html-unescape applies HTML unescaping to special characters.
  • lower maps all Unicode letters in the given value to their lower case.
  • upper maps all Unicode letters in the given value to their upper case.
  • title maps the first letter of each word to their upper case.
  • trim removes the whitespaces at the beginning and at the end of the given value.
  • trim-left removes the whitespaces at the beginning of the given value.
  • trim-right removes the whitespaces at the end of the given value.
  • url-escape applies URL escaping to special characters.
  • url-unescape applies URL unescaping to special characters.

Custom Checkers

To define a custom checker, you need to create a new function with the following parameters:

func CustomChecker(value, parent reflect.Value) error {
    return nil
}

type MakeFunc You also need to create a make function that takes the checker configuration and returns a reference to the checker function.

func CustomMaker(params string) CheckFunc {
    return CustomChecker
}

Finally, you need to call the Register function to register your custom checker.

checker.Register("custom-checker", CustomMaker)

Once you have registered your custom checker, you can use it by simply specifying its name.

type User struct {
    Username string `checkers:"custom-checker"`
}

checker

import "github.com/cinar/checker"

Package checker is a Go library for validating user input through struct tags.

Copyright (c) 2023-2024 Onur Cinar. Use of this source code is governed by a MIT-style license that can be found in the LICENSE file. https://github.com/cinar/checker

Index

Variables

ErrNotASCII indicates that the given string contains non-ASCII characters.

var ErrNotASCII = errors.New("please use standard English characters only")

ErrNotAlphanumeric indicates that the given string contains non-alphanumeric characters.

var ErrNotAlphanumeric = errors.New("please use only letters and numbers")

ErrNotCidr indicates that the given value is not a valid CIDR.

var ErrNotCidr = errors.New("please enter a valid CIDR")

ErrNotCreditCard indicates that the given value is not a valid credit card number.

var ErrNotCreditCard = errors.New("please enter a valid credit card number")

ErrNotDigits indicates that the given string contains non-digit characters.

var ErrNotDigits = errors.New("please enter a valid number")

ErrNotEmail indicates that the given string is not a valid email.

var ErrNotEmail = errors.New("please enter a valid email address")

ErrNotFqdn indicates that the given string is not a valid FQDN.

var ErrNotFqdn = errors.New("please enter a valid domain name")

ErrNotIP indicates that the given value is not an IP address.

var ErrNotIP = errors.New("please enter a valid IP address")

ErrNotIPV4 indicates that the given value is not an IPv4 address.

var ErrNotIPV4 = errors.New("please enter a valid IPv4 address")

ErrNotIPV6 indicates that the given value is not an IPv6 address.

var ErrNotIPV6 = errors.New("please enter a valid IPv6 address")

ErrNotISBN indicates that the given value is not a valid ISBN.

var ErrNotISBN = errors.New("please enter a valid ISBN number")

ErrNotLuhn indicates that the given number is not valid based on the Luhn algorithm.

var ErrNotLuhn = errors.New("please enter a valid LUHN")

ErrNotMac indicates that the given value is not an MAC address.

var ErrNotMac = errors.New("please enter a valid MAC address")

ErrNotMatch indicates that the given string does not match the regexp pattern.

var ErrNotMatch = errors.New("please enter a valid input")

ErrNotSame indicates that the given two values are not equal to each other.

var ErrNotSame = errors.New("does not match the other")

ErrNotURL indicates that the given value is not a valid URL.

var ErrNotURL = errors.New("please enter a valid URL")

ErrRequired indicates that the required value is missing.

var ErrRequired = errors.New("is required")

func FailIfNoPanic

func FailIfNoPanic(t *testing.T)

FailIfNoPanic fails if test didn't panic. Use this function with the defer.

func IsASCII

func IsASCII(value string) error

IsASCII checks if the given string consists of only ASCII characters.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsASCII("Checker")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsAlphanumeric

func IsAlphanumeric(value string) error

IsAlphanumeric checks if the given string consists of only alphanumeric characters.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsAlphanumeric("ABcd1234")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsAmexCreditCard

func IsAmexCreditCard(number string) error

IsAmexCreditCard checks if the given valie is a valid AMEX credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsAmexCreditCard("378282246310005")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsAnyCreditCard

func IsAnyCreditCard(number string) error

IsAnyCreditCard checks if the given value is a valid credit card number.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsAnyCreditCard("6011111111111117")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsCidr

func IsCidr(value string) error

IsCidr checker checks if the value is a valid CIDR notation IP address and prefix length.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsCidr("2001:db8::/32")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsDigits

func IsDigits(value string) error

IsDigits checks if the given string consists of only digit characters.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsDigits("1234")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsDinersCreditCard

func IsDinersCreditCard(number string) error

IsDinersCreditCard checks if the given valie is a valid Diners credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsDinersCreditCard("36227206271667")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsDiscoverCreditCard

func IsDiscoverCreditCard(number string) error

IsDiscoverCreditCard checks if the given valie is a valid Discover credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsDiscoverCreditCard("6011111111111117")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsEmail

func IsEmail(email string) error

IsEmail checks if the given string is an email address.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsEmail("[email protected]")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsFqdn

func IsFqdn(domain string) error

IsFqdn checks if the given string is a fully qualified domain name.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsFqdn("zdo.com")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsIP

func IsIP(value string) error

IsIP checks if the given value is an IP address.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsIP("2001:db8::68")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsIPV4

func IsIPV4(value string) error

IsIPV4 checks if the given value is an IPv4 address.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsIPV4("192.168.1.1")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsIPV6

func IsIPV6(value string) error

IsIPV6 checks if the given value is an IPv6 address.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsIPV6("2001:db8::68")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsISBN

func IsISBN(value string) error

IsISBN checks if the given value is a valid ISBN number.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsISBN("1430248270")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsISBN10

func IsISBN10(value string) error

IsISBN10 checks if the given value is a valid ISBN-10 number.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsISBN10("1430248270")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsISBN13

func IsISBN13(value string) error

IsISBN13 checks if the given value is a valid ISBN-13 number.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsISBN13("9781430248279")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsJcbCreditCard

func IsJcbCreditCard(number string) error

IsJcbCreditCard checks if the given valie is a valid JCB 15 credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsJcbCreditCard("3530111333300000")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsLuhn

func IsLuhn(number string) error

IsLuhn checks if the given number is valid based on the Luhn algorithm.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsLuhn("4012888888881881")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsMac

func IsMac(value string) error

IsMac checks if the given value is a valid an IEEE 802 MAC-48, EUI-48, EUI-64, or a 20-octet IP over InfiniBand link-layer address.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsMac("00:00:5e:00:53:01")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsMasterCardCreditCard

func IsMasterCardCreditCard(number string) error

IsMasterCardCreditCard checks if the given valie is a valid MasterCard credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsMasterCardCreditCard("5555555555554444")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsMax

func IsMax(value interface{}, max float64) error

IsMax checks if the given value is below than the given maximum.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	quantity := 5

	err := checker.IsMax(quantity, 10)
	if err != nil {
		// Send the errors back to the user
	}
}

func IsMaxLength

func IsMaxLength(value interface{}, maxLength int) error

IsMaxLength checks if the length of the given value is less than the given maximum length.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	s := "1234"

	err := checker.IsMaxLength(s, 4)
	if err != nil {
		// Send the errors back to the user
	}
}

func IsMin

func IsMin(value interface{}, min float64) error

IsMin checks if the given value is above than the given minimum.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	age := 45

	err := checker.IsMin(age, 21)
	if err != nil {
		// Send the errors back to the user
	}
}

func IsMinLength

func IsMinLength(value interface{}, minLength int) error

IsMinLength checks if the length of the given value is greather than the given minimum length.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	s := "1234"

	err := checker.IsMinLength(s, 4)
	if err != nil {
		// Send the errors back to the user
	}
}

func IsRequired

func IsRequired(v interface{}) error

IsRequired checks if the given required value is present.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	var name string

	err := checker.IsRequired(name)
	if err != nil {
		// Send the err back to the user
	}
}

func IsURL

func IsURL(value string) error

IsURL checks if the given value is a valid URL.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsURL("https://zdo.com")
	if err != nil {
		// Send the errors back to the user
	}
}

func IsUnionPayCreditCard

func IsUnionPayCreditCard(number string) error

IsUnionPayCreditCard checks if the given valie is a valid UnionPay credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsUnionPayCreditCard("6200000000000005")

	if err != nil {
		// Send the errors back to the user
	}
}

func IsVisaCreditCard

func IsVisaCreditCard(number string) error

IsVisaCreditCard checks if the given valie is a valid Visa credit card.

Example 

package main

import (
	"github.com/cinar/checker"
)

func main() {
	err := checker.IsVisaCreditCard("4111111111111111")

	if err != nil {
		// Send the errors back to the user
	}
}

func Register

func Register(name string, maker MakeFunc)

Register registers the given checker name and the maker function.

type CheckFunc

CheckFunc defines the signature for the checker functions.

type CheckFunc func(value, parent reflect.Value) error

func MakeRegexpChecker

func MakeRegexpChecker(expression string, invalidError error) CheckFunc

MakeRegexpChecker makes a regexp checker for the given regexp expression with the given invalid result.

type Errors

Errors provides a mapping of the checker errors keyed by the field names.

type Errors map[string]error

func Check

func Check(s interface{}) (Errors, bool)

Check function checks the given struct based on the checkers listed in field tag names.

type MakeFunc

MakeFunc defines the signature for the checker maker functions.

type MakeFunc func(params string) CheckFunc

func MakeRegexpMaker

func MakeRegexpMaker(expression string, invalidError error) MakeFunc

MakeRegexpMaker makes a regexp checker maker for the given regexp expression with the given invalid result.

Generated by gomarkdoc

Contributing to the Project

Anyone can contribute to Checkers library. Please make sure to read our Contributor Covenant Code of Conduct guide first. Follow the How to Contribute to Checker to contribute.

License

This library is free to use, modify, and distribute under the terms of the MIT license. The full license text can be found in the LICENSE file.

The MIT license is a permissive license that allows you to do almost anything with the library, as long as you retain the copyright notice and the license text. This means that you can use the library in commercial products, modify it, and redistribute it without having to ask for permission from the authors.

The LICENSE file is located in the root directory of the library. You can open it in a text editor to read the full license text.