forms

README

forms

forms provides a way to parse http Request forms using a schema

Getting Started

The forms package can be added to a project by running:

go get cattlecloud.net/go/forms@latest

import "cattlecloud.net/go/forms"

Examples

parsing http request

var (
  name string
  age  int
)

err := forms.Parse(request, forms.Schema{
  "NAME": forms.String(&name),
  "AGE":  forms.Int(&age),
})

about requests

Typically the HTTP request will be given to you in the form of an http handler, e.g.

func(w http.ResponseWriter, r *http.Request) {
  _ = r.ParseForm()
  // now r form data is available to parse
}

License

The cattlecloud.net/go/forms module is open source under the BSD license.

Documentation

Overview

Package forms provides a way to safely and conveniently extract html Form data using a definied schema.

Index

• Variables
• func Parse(r *http.Request, schema Schema) error
• func ParseValues(data url.Values, schema Schema) error
• type IntType
• type Parser
  • func Bool(b *bool) Parser
  • func BoolOr(b *bool, alt bool) Parser
  • func Float(f *float64) Parser
  • func FloatOr(f *float64, alt float64) Parser
  • func Int[T IntType](i *T) Parser
  • func IntOr[T IntType](i *T, alt T) Parser
  • func Secret(s **conceal.Text) Parser
  • func String[T StringType](s *T) Parser
  • func StringOr[T StringType](s *T, alt T) Parser
• type Schema
• type StringType

Variables

var (
	ErrNoValue         = errors.New("expected value to exist")
	ErrMulitpleValues  = errors.New("expected only one value to exist")
	ErrFieldNotPresent = errors.New("requested field does not exist")
	ErrParseFailure    = errors.New("could not parse value")
)

Functions

func Parse

func Parse(r *http.Request, schema Schema) error

Parse uses the given Schema to parse the HTTP form values in the given HTTP Request. If the values of the form do not match the schema, or required values are missing, an error is returned.

func ParseValues

func ParseValues(data url.Values, schema Schema) error

ParseValues uses the given Schema to parse the values in the given url.Values. If the values do not match the schema, or required values are missing, an error is returned.

Types

type IntType

type IntType interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

IntType represents any type compatible with the Go integer built-in types, to be used as a destination for writing the value of a form value.

type Parser

type Parser interface {
	Parse([]string) error
}

A Parser implementation is capable of extracting a value from the value of an url.Values, which is a slice of string.

func Bool

func Bool(b *bool) Parser

Bool is used to extract a form data value into a Go bool. If the value is not a bool or is missing than an error is returned during parsing.

func BoolOr

func BoolOr(b *bool, alt bool) Parser

BoolOr is used to extract a form data value into a Go bool. If the value is missing, then the alt value is used instead.

func Float

func Float(f *float64) Parser

Float is used to extract a form data value into a Go float64. If the value is not a float or is missing then an error is returned during parsing.

func FloatOr

func FloatOr(f *float64, alt float64) Parser

FloatOr is used to extract a form data value into a Go float64. If the value is missing, then the alt value is used instead.

func Int

func Int[T IntType](i *T) Parser

Int is used to extract a form data value into a Go int. If the value is not an int or is missing then an error is returned during parsing.

func IntOr

func IntOr[T IntType](i *T, alt T) Parser

IntOr is used to extract a form data value into a Go int. If the value is missing, then the alt value is used instead.

func Secret

func Secret(s **conceal.Text) Parser

Secret is used to extract a form data value into a Go conceal.Text. If the value is missing then an error is returned during parsing.

func String

func String[T StringType](s *T) Parser

String is used to extract a form data value into a Go string. If the value is not a string or is missing then an error is returned during parsing.

func StringOr

func StringOr[T StringType](s *T, alt T) Parser

StringOr is used to extract a form data value into a Go string. If the value is missing, then the alt value is used instead.

type Schema

type Schema map[string]Parser

A Schema describes how a set of url.Values should be parsed. Typically these are coming from an http.Request.Form from inside an http.Handler responding to an inbound request.

type StringType

type StringType interface {
	~string
}

StringType represents any type compatible with the Go string built-in type, to be used as a destination for writing the value of an environment variable.