scanner

README

Scanner

Scanner is a utility package to extract certain values and cast them to usable values in the context of http servers. It can extract request bodies, form values, url queries, cookies and headers. Scanner defines a Scanner interface for you to extend it to your own needs.

type Scanner interface {
  Scan(any) error
}

Example

An example that extracts header values from an http.Header object.

type Params struct {
  // provide the header name in the field tag
  Language string `header:"accept-language"`
}

// ...

// Create your instance
p := &Params{}
// Provide the request headers
s := scanner.NewHeaderScanner(r.Headers())
if err := s.Scan(p); err != nil {
  // handle error
}
// p.Language -> r.Headers().Get("Accept-Language")

You can compose your scanners. There are a handful of pre-built scanners for the most common of use cases.

• scanner.JsonScanner: Scans json data from an io.Reader
• scanner.HeaderScanner: Scans header data from an *http.Header
• scanner.QueryScanner: Scans url query values from a *url.Values
• scanner.FormScanner: Scans form data from a *url.Values
• scanner.CookieScanner: Scans cookies from a http.CookieJar
• scanner.MultipartScanner: Scans multipart form data from a scanner.MultipartValues
• scanner.ImageScanner: Scans multipart images from a scanner.MultipartValues

eg.:

type Params struct {
  IDs      []string `query:"ids"`
  Language string   `header:"accept-language"`
  Token    string   `cookie:"token"`
}

// ...

// Create your instance
p := &Params{}
var s scanner.Scanner

s = scanner.NewQueryScanner(/* url.Values */)
s.Scan(p) // Don't forget to handle errors

s = scanner.NewHeaderScanner(/* http.Header */)
s.Scan(p) // Don't forget to handle errors

s = scanner.NewCookieScanner(/* http.CookieJar */)
s.Scan(p) // Don't forget to handle errors

Or, alternatively, you can use a scanner.PipeScanner to streamline the process.

type Params struct {
  IDs      []string `query:"ids"`
  Language string   `header:"accept-language"`
  Token    string   `cookie:"token"`
}

// ...

// Create your instance
p := &Params{}
s := scanner.NewPipeScanner(
  scanner.NewQueryScanner(/* url.Values */),
  scanner.NewHeaderScanner(/* http.Header */),
  scanner.NewCookieScanner(/* http.CookieJar */),
)
s.Scan(p) // Don't forget to handle errors

This will populate your struct's fields with available values.

Documentation

Index

• type Cookie
  • func NewCookie(jar http.CookieJar, url *url.URL) *Cookie
  • func (v Cookie) Get(key string) any
  • func (s *Cookie) Scan(v any) error
• type Directory
  • func NewDirectory(fsys fs.FS) (*Directory, error)
  • func (s *Directory) Cast(from any, to reflect.Type) (any, error)
  • func (s *Directory) Get(key string) any
  • func (s *Directory) Scan(v any) error
• type Form
  • func NewForm(v *url.Values) *Form
  • func (v Form) Cast(from any, to reflect.Type) (any, error)
  • func (v Form) Get(key string) any
  • func (s *Form) Scan(v any) error
• type Header
  • func NewHeader(h *http.Header) *Header
  • func (h *Header) Get(key string) any
  • func (s *Header) Scan(v any) error
• type Image
  • func NewImage(v *MultipartValues) *Image
  • func (v Image) Get(key string) any
  • func (s *Image) Scan(v any) error
• type JSON
  • func NewJSON(r io.Reader) *JSON
  • func NewJSONBytes(b []byte) *JSON
  • func (s *JSON) Scan(v any) error
• type Multipart
  • func NewMultipart(v *MultipartValues) *Multipart
  • func (s *Multipart) Scan(v any) error
• type MultipartParser
• type MultipartValues
  • func MultipartValuesFromParser(p MultipartParser, size int64, names ...string) (*MultipartValues, error)
  • func (v MultipartValues) Get(key string) any
• type Pipe
  • func NewPipe(scanners ...Scanner) *Pipe
  • func (s *Pipe) Scan(v any) error
• type Query
  • func NewQuery(v *url.Values) *Query
  • func (v Query) Cast(from any, to reflect.Type) (any, error)
  • func (v Query) Get(key string) any
  • func (s *Query) Scan(v any) error
• type Scanner

Types

type Cookie

type Cookie struct {
	http.CookieJar
	// contains filtered or unexported fields
}

A scanner to scan http cookies for a url from a `http.CookieJar` to a struct

func NewCookie

func NewCookie(jar http.CookieJar, url *url.URL) *Cookie

func (Cookie) Get

func (v Cookie) Get(key string) any

func (*Cookie) Scan

func (s *Cookie) Scan(v any) error

Scans the cookie values onto v

type Directory

type Directory struct {
	// contains filtered or unexported fields
}

A scanner to scan os file's content to a struct

func NewDirectory

func NewDirectory(fsys fs.FS) (*Directory, error)

func (*Directory) Cast

func (s *Directory) Cast(from any, to reflect.Type) (any, error)

func (*Directory) Get

func (s *Directory) Get(key string) any

func (*Directory) Scan

func (s *Directory) Scan(v any) error

type Form

type Form struct {
	*url.Values
}

A scanner to scan form values from a `*url.Values` to a struct

func NewForm

func NewForm(v *url.Values) *Form

func (Form) Cast

func (v Form) Cast(from any, to reflect.Type) (any, error)

func (Form) Get

func (v Form) Get(key string) any

func (*Form) Scan

func (s *Form) Scan(v any) error

Scans the form data onto v

type Header

type Header struct {
	*http.Header
}

A scanner to scan header values from an `http.Header` to a struct

func NewHeader

func NewHeader(h *http.Header) *Header

func (*Header) Get

func (h *Header) Get(key string) any

func (*Header) Scan

func (s *Header) Scan(v any) error

Scans the headers onto v

type Image

type Image struct {
	Files map[string]multipart.File
}

func NewImage

func NewImage(v *MultipartValues) *Image

func (Image) Get

func (v Image) Get(key string) any

func (*Image) Scan

func (s *Image) Scan(v any) error

Scans the multipart form data and turns them into image.Image and sets v

type JSON

type JSON struct {
	// contains filtered or unexported fields
}

A scanner to scan json value from an `io.Reader` to a struct

func NewJSON

func NewJSON(r io.Reader) *JSON

func NewJSONBytes

func NewJSONBytes(b []byte) *JSON

func (*JSON) Scan

func (s *JSON) Scan(v any) error

Scans the json onto v

type Multipart

type Multipart struct {
	// contains filtered or unexported fields
}

A scanner to scan multipart form values, files, from a `*scanner.MultipartValues` to a struct You can create a `*scanner.MultipartValues` instance with the `scanner.MultipartValuesFromParser` function.

func NewMultipart

func NewMultipart(v *MultipartValues) *Multipart

func (*Multipart) Scan

func (s *Multipart) Scan(v any) error

Scans the multipart form data onto v

type MultipartParser

type MultipartParser interface {
	ParseMultipartForm(int64) error
	FormFile(string) (multipart.File, *multipart.FileHeader, error)
}

type MultipartValues

type MultipartValues struct {
	Files map[string]multipart.File
}

func MultipartValuesFromParser

func MultipartValuesFromParser(p MultipartParser, size int64, names ...string) (*MultipartValues, error)

MultipartValuesFromParser takes a generic parser that is usually an `*http.Request` and returns `*scanner.MultipartValues` to use it with a `scanner.MultipartScanner` or `scanner.ImageScanner`

func (MultipartValues) Get

func (v MultipartValues) Get(key string) any

type Pipe

type Pipe []Scanner

func NewPipe

func NewPipe(scanners ...Scanner) *Pipe

func (*Pipe) Scan

func (s *Pipe) Scan(v any) error

Runs given scanners in sequence

type Query

type Query struct {
	*url.Values
}

A scanner to scan url query values from a `*url.Values` to a struct

func NewQuery

func NewQuery(v *url.Values) *Query

func (Query) Cast

func (v Query) Cast(from any, to reflect.Type) (any, error)

func (Query) Get

func (v Query) Get(key string) any

func (*Query) Scan

func (s *Query) Scan(v any) error

Scans the query values onto v

type Scanner

type Scanner interface {
	Scan(any) error
}

Scanner interface resembles a json parser, it populates the given struct with available values based on its field tags. It should return an error when v is not a struct.