README
¶
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{}
mistakes, valid := checker.Check(person)
if !valid {
// Send the mistakes 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
result := checker.IsRequired(name)
if result != ResultValid {
// 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) Result {
return ResultValid
}
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"`
}
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.
Documentation
¶
Overview ¶
Package checker is a Go library for validating user input through struct tags.
https://github.com/cinar/checker
Copyright 2023 Onur Cinar. All rights reserved. Use of this source code is governed by a MIT-style license that can be found in the LICENSE file.
Index ¶
- Constants
- func FailIfNoPanic(t *testing.T)
- func Register(name string, maker MakeFunc)
- type CheckFunc
- type MakeFunc
- type Mistakes
- type Result
- func IsASCII(value string) Result
- func IsAlphanumeric(value string) Result
- func IsAmexCreditCard(number string) Result
- func IsAnyCreditCard(number string) Result
- func IsCidr(value string) Result
- func IsDigits(value string) Result
- func IsDinersCreditCard(number string) Result
- func IsDiscoverCreditCard(number string) Result
- func IsEmail(email string) Result
- func IsFqdn(domain string) Result
- func IsIP(value string) Result
- func IsIPV4(value string) Result
- func IsIPV6(value string) Result
- func IsISBN(value string) Result
- func IsISBN10(value string) Result
- func IsISBN13(value string) Result
- func IsJcbCreditCard(number string) Result
- func IsLuhn(number string) Result
- func IsMac(value string) Result
- func IsMasterCardCreditCard(number string) Result
- func IsMax(value interface{}, max float64) Result
- func IsMaxLength(value interface{}, maxLength int) Result
- func IsMin(value interface{}, min float64) Result
- func IsMinLength(value interface{}, minLength int) Result
- func IsRequired(v interface{}) Result
- func IsURL(value string) Result
- func IsUnionPayCreditCard(number string) Result
- func IsVisaCreditCard(number string) Result
Examples ¶
- IsASCII
- IsAlphanumeric
- IsAmexCreditCard
- IsAnyCreditCard
- IsCidr
- IsDigits
- IsDinersCreditCard
- IsDiscoverCreditCard
- IsEmail
- IsFqdn
- IsIP
- IsIPV4
- IsIPV6
- IsISBN
- IsISBN10
- IsISBN13
- IsJcbCreditCard
- IsLuhn
- IsMac
- IsMasterCardCreditCard
- IsMax
- IsMaxLength
- IsMin
- IsMinLength
- IsRequired
- IsURL
- IsUnionPayCreditCard
- IsVisaCreditCard
Constants ¶
const CheckerASCII = "ascii"
CheckerASCII is the name of the checker.
const CheckerAlphanumeric = "alphanumeric"
CheckerAlphanumeric is the name of the checker.
const CheckerCidr = "cidr"
CheckerCidr is the name of the checker.
const CheckerCreditCard = "credit-card"
CheckerCreditCard is the name of the checker.
const CheckerDigits = "digits"
CheckerDigits is the name of the checker.
const CheckerEmail = "email"
CheckerEmail is the name of the checker.
const CheckerFqdn = "fqdn"
CheckerFqdn is the name of the checker.
const CheckerIP = "ip"
CheckerIP is the name of the checker.
const CheckerIPV4 = "ipv4"
CheckerIPV4 is the name of the checker.
const CheckerIPV6 = "ipv6"
CheckerIPV6 is the name of the checker.
const CheckerISBN = "isbn"
CheckerISBN is the name of the checker.
const CheckerLuhn = "luhn"
CheckerLuhn is the name of the checker.
const CheckerMac = "mac"
CheckerMac is the name of the checker.
const CheckerMax = "max"
CheckerMax is the name of the checker.
const CheckerMaxLength = "max-length"
CheckerMaxLength is the name of the checker.
const CheckerMin = "min"
CheckerMin is the name of the checker.
const CheckerMinLength = "min-length"
CheckerMinLength is the name of the checker.
const CheckerRegexp = "regexp"
CheckerRegexp is the name of the checker.
const CheckerRequired = "required"
CheckerRequired is the name of the checker.
const CheckerSame = "same"
CheckerSame is the name of the checker.
const CheckerURL = "url"
CheckerURL is the name of the checker.
const NormalizerHTMLEscape = "html-escape"
NormalizerHTMLEscape is the name of the normalizer.
const NormalizerHTMLUnescape = "html-unescape"
NormalizerHTMLUnescape is the name of the normalizer.
const NormalizerLower = "lower"
NormalizerLower is the name of the normalizer.
const NormalizerTitle = "title"
NormalizerTitle is the name of the normalizer.
const NormalizerTrim = "trim"
NormalizerTrim is the name of the normalizer.
const NormalizerTrimLeft = "trim-left"
NormalizerTrimLeft is the name of the normalizer.
const NormalizerTrimRight = "trim-right"
NormalizerTrimRight is the name of the normalizer.
const NormalizerURLEscape = "url-escape"
NormalizerURLEscape is the name of the normalizer.
const NormalizerURLUnescape = "url-unescape"
NormalizerURLUnescape is the name of the normalizer.
const NormalizerUpper = "upper"
NormalizerUpper is the name of the normalizer.
const ResultNotASCII = "NOT_ASCII"
ResultNotASCII indicates that the given string contains non-ASCII characters.
const ResultNotAlphanumeric = "NOT_ALPHANUMERIC"
ResultNotAlphanumeric indicates that the given string contains non-alphanumeric characters.
const ResultNotCidr = "NOT_CIDR"
ResultNotCidr indicates that the given value is not a valid CIDR.
const ResultNotCreditCard = "NOT_CREDIT_CARD"
ResultNotCreditCard indicates that the given value is not a valid credit card number.
const ResultNotDigits = "NOT_DIGITS"
ResultNotDigits indicates that the given string contains non-digit characters.
const ResultNotEmail = "NOT_EMAIL"
ResultNotEmail indicates that the given string is not a valid email.
const ResultNotFqdn = "NOT_FQDN"
ResultNotFqdn indicates that the given string is not a valid FQDN.
const ResultNotIP = "NOT_IP"
ResultNotIP indicates that the given value is not an IP address.
const ResultNotIPV4 = "NOT_IP_V4"
ResultNotIPV4 indicates that the given value is not an IPv4 address.
const ResultNotIPV6 = "NOT_IP_V6"
ResultNotIPV6 indicates that the given value is not an IPv6 address.
const ResultNotISBN = "NOT_ISBN"
ResultNotISBN indicates that the given value is not a valid ISBN.
const ResultNotLuhn = "NOT_LUHN"
ResultNotLuhn indicates that the given number is not valid based on the Luhn algorithm.
const ResultNotMac = "NOT_MAC"
ResultNotMac indicates that the given value is not an MAC address.
const ResultNotMatch = "NOT_MATCH"
ResultNotMatch indicates that the given string does not match the regexp pattern.
const ResultNotMax = "NOT_MIN"
ResultNotMax indicates that the given value is above the defined maximum.
const ResultNotMaxLength = "NOT_MAX_LENGTH"
ResultNotMaxLength indicates that the length of the given value is above the defined number.
const ResultNotMin = "NOT_MIN"
ResultNotMin indicates that the given value is below the defined minimum.
const ResultNotMinLength = "NOT_MIN_LENGTH"
ResultNotMinLength indicates that the length of the given value is below the defined number.
const ResultNotSame = "NOT_SAME"
ResultNotSame indicates that the given two values are not equal to each other.
const ResultNotURL = "NOT_URL"
ResultNotURL indicates that the given value is not a valid URL.
Variables ¶
This section is empty.
Functions ¶
func FailIfNoPanic ¶
FailIfNoPanic fails if test didn't panic. Use this function with the defer.
Types ¶
type CheckFunc ¶
CheckFunc defines the checker function.
func MakeRegexpChecker ¶
MakeRegexpChecker makes a regexp checker for the given regexp expression with the given invalid result.
type MakeFunc ¶
MakeFunc defines the maker function.
func MakeRegexpMaker ¶
MakeRegexpMaker makes a regexp checker maker for the given regexp expression with the given invalid result.
type Result ¶
type Result string
Result is a unique textual identifier for the mistake.
const ResultRequired Result = "REQUIRED"
ResultRequired indicates that the required value is missing.
const ResultValid Result = "VALID"
ResultValid result indicates that the user input is valid.
func IsASCII ¶
IsASCII checks if the given string consists of only ASCII characters.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsASCII("Checker")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsAlphanumeric ¶
IsAlphanumeric checks if the given string consists of only alphanumeric characters.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsAlphanumeric("ABcd1234")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsAmexCreditCard ¶
IsAmexCreditCard checks if the given valie is a valid AMEX credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsAmexCreditCard("378282246310005")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsAnyCreditCard ¶
IsAnyCreditCard checks if the given value is a valid credit card number.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsAnyCreditCard("6011111111111117")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsCidr ¶
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() {
result := checker.IsCidr("2001:db8::/32")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsDigits ¶
IsDigits checks if the given string consists of only digit characters.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsDigits("1234")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsDinersCreditCard ¶
IsDinersCreditCard checks if the given valie is a valid Diners credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsDinersCreditCard("36227206271667")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsDiscoverCreditCard ¶ added in v1.2.0
IsDiscoverCreditCard checks if the given valie is a valid Discover credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsDiscoverCreditCard("6011111111111117")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsEmail ¶
IsEmail checks if the given string is an email address.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsEmail("user@zdo.com")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsFqdn ¶
IsFqdn checks if the given string is a fully qualified domain name.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsFqdn("zdo.com")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsIP ¶
IsIP checks if the given value is an IP address.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsIP("2001:db8::68")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsIPV4 ¶
IsIPV4 checks if the given value is an IPv4 address.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsIPV4("192.168.1.1")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsIPV6 ¶
IsIPV6 checks if the given value is an IPv6 address.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsIPV6("2001:db8::68")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsISBN ¶ added in v1.1.0
IsISBN checks if the given value is a valid ISBN number.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsISBN("1430248270")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsISBN10 ¶ added in v1.1.0
IsISBN10 checks if the given value is a valid ISBN-10 number.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsISBN10("1430248270")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsISBN13 ¶ added in v1.1.0
IsISBN13 checks if the given value is a valid ISBN-13 number.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsISBN13("9781430248279")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsJcbCreditCard ¶
IsJcbCreditCard checks if the given valie is a valid JCB 15 credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsJcbCreditCard("3530111333300000")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsLuhn ¶
IsLuhn checks if the given number is valid based on the Luhn algorithm.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsLuhn("4012888888881881")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMac ¶
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() {
result := checker.IsMac("00:00:5e:00:53:01")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMasterCardCreditCard ¶
IsMasterCardCreditCard checks if the given valie is a valid MasterCard credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsMasterCardCreditCard("5555555555554444")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMax ¶
IsMax checks if the given value is below than the given maximum.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
quantity := 5
result := checker.IsMax(quantity, 10)
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMaxLength ¶
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"
result := checker.IsMaxLength(s, 4)
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMin ¶
IsMin checks if the given value is above than the given minimum.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
age := 45
result := checker.IsMin(age, 21)
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsMinLength ¶
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"
result := checker.IsMinLength(s, 4)
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsRequired ¶
func IsRequired(v interface{}) Result
IsRequired checks if the given required value is present.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
var name string
result := checker.IsRequired(name)
if result != checker.ResultValid {
// Send the result back to the user
}
}
Output:
func IsURL ¶ added in v1.1.0
IsURL checks if the given value is a valid URL.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsURL("https://zdo.com")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsUnionPayCreditCard ¶
IsUnionPayCreditCard checks if the given valie is a valid UnionPay credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsUnionPayCreditCard("6200000000000005")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
func IsVisaCreditCard ¶
IsVisaCreditCard checks if the given valie is a valid Visa credit card.
Example ¶
package main
import (
"github.com/cinar/checker"
)
func main() {
result := checker.IsVisaCreditCard("4111111111111111")
if result != checker.ResultValid {
// Send the mistakes back to the user
}
}
Output:
Source Files
¶
- alphanumeric.go
- ascii.go
- checker.go
- cidr.go
- credit_card.go
- digits.go
- email.go
- fqdn.go
- html_escape.go
- html_unescape.go
- ip.go
- ipv4.go
- ipv6.go
- isbn.go
- lower.go
- luhn.go
- mac.go
- max.go
- maxlength.go
- min.go
- minlenght.go
- regexp.go
- required.go
- same.go
- test_helper.go
- title.go
- trim.go
- trim_left.go
- trim_right.go
- upper.go
- url.go
- url_escape.go
- url_unescape.go