urlquery

README

Introduction

A URL Query string Encoder and Parser based on go.

• Parse from URL Query string to go structure
• Encode from go structure to URL Query string

Keywords

x-www-form-urlencoded Query Encoder URL-Query Http-Query go

Feature

• Support full go structure Translation
  • Basic Structure: Int[8,16,32,64] Uint[8,16,32,64] String Bool Float[32,64] Byte Rune
  • Complex Structure: Array Slice Map Struct
  • Nested Struct with above Basic or Complex Structure
• Support top-level structure: Map, Slice or Array, not only Struct
• Support self-defined URL Query Encode rule example
• Support self-defined key name relation rule example
• Support self-defined value encode and decode function example
• Support to control whether ignoring Zero-value of struct member example

Quick Start

More to see example

package main

import (
	"github.com/hetiansu5/urlquery"
	"fmt"
)

type SimpleChild struct {
	Status bool `query:"status"`
	Name   string
}

type SimpleData struct {
	Id         int
	Name       string          `query:"name"`
	Child      SimpleChild
	Params     map[string]int8 `query:"p"`
	Array      [3]uint16
}

func main() {
	data := SimpleData{
		Id:   2,
		Name: "http://localhost/test.php?id=2",
		Child: SimpleChild{
			Status: true,
		},
		Params: map[string]int8{
			"one": 1,
		},
		Array: [3]uint16{2, 3, 300},
	}

	//Marshal: from go structure to url query string
	bytes, _ := urlquery.Marshal(data)
	//output Id=2&name=http%3A%2F%2Flocalhost%2Ftest.php%3Fid%3D2&Child%5Bstatus%5D=1&p%5Bone%5D=1&Array%5B%5D=2&Array%5B%5D=3&Array%5B%5D=300
	fmt.Println(string(bytes))

	//Unmarshal: from url query  string to go structure
	v := &SimpleData{}
	urlquery.Unmarshal(bytes, v)
	//output {Id:2, Name:"http://localhost/test.php?id=2", Child: SimpleChild{Status:true}, Params:map[one:1], Array:[2, 3, 300]}
	fmt.Println(*v)
}

Attention

• For Map structure, Marshal supports map[Basic]Basic|Complex, but Unmarshal just supports map[Basic]Basic
• Default: ignoring Zero-value of struct member. You can enable it with Option
• Remember that: Byte is actually uint8, Rune is actually int32

License

MIT

Documentation

Index

• Constants
• func Marshal(data interface{}) ([]byte, error)
• func NewEncoder(opts ...Option) *encoder
• func NewParser(opts ...Option) *parser
• func SetGlobalQueryEncoder(u QueryEncoder)
• func Unmarshal(data []byte, v interface{}) error
• type DefaultQueryEncoder
  • func (u DefaultQueryEncoder) Escape(s string) string
  • func (u DefaultQueryEncoder) UnEscape(s string) (string, error)
• type ErrInvalidMapKeyType
  • func (e ErrInvalidMapKeyType) Error() string
• type ErrInvalidMapValueType
  • func (e ErrInvalidMapValueType) Error() string
• type ErrInvalidUnmarshalError
  • func (e ErrInvalidUnmarshalError) Error() string
• type ErrTranslated
  • func (e ErrTranslated) Error() string
• type ErrUnhandledType
  • func (e ErrUnhandledType) Error() string
• type ErrUnsupportedBitSize
  • func (e ErrUnsupportedBitSize) Error() string
• type Option
  • func WithNeedEmptyValue(c bool) Option
  • func WithQueryEncoder(u QueryEncoder) Option
• type QueryEncoder

Constants

const (
	// SymbolEqual is key character of querystring
	SymbolEqual = "="
	// SymbolAnd is key character of querystring
	SymbolAnd = "&"
)

Functions

func Marshal

func Marshal(data interface{}) ([]byte, error)

Marshal do encoding go structure to string it is thread safety

func NewEncoder

func NewEncoder(opts ...Option) *encoder

NewEncoder return new encoder object do some option initialization

func NewParser

func NewParser(opts ...Option) *parser

NewParser make a new parser object do some option initialization

func SetGlobalQueryEncoder

func SetGlobalQueryEncoder(u QueryEncoder)

SetGlobalQueryEncoder set global query encoder

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal is supposed to decode string to go structure It is thread safety

Types

type DefaultQueryEncoder

type DefaultQueryEncoder struct{}

A DefaultQueryEncoder is a default URL-Encoder

func (DefaultQueryEncoder) Escape

func (u DefaultQueryEncoder) Escape(s string) string

Escape text

func (DefaultQueryEncoder) UnEscape

func (u DefaultQueryEncoder) UnEscape(s string) (string, error)

UnEscape text

type ErrInvalidMapKeyType

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

An ErrInvalidMapKeyType is a customized error

func (ErrInvalidMapKeyType) Error

func (e ErrInvalidMapKeyType) Error() string

type ErrInvalidMapValueType

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

An ErrInvalidMapValueType is a customized error

func (ErrInvalidMapValueType) Error

func (e ErrInvalidMapValueType) Error() string

type ErrInvalidUnmarshalError

type ErrInvalidUnmarshalError struct{}

An ErrInvalidUnmarshalError is a customized error

func (ErrInvalidUnmarshalError) Error

func (e ErrInvalidUnmarshalError) Error() string

type ErrTranslated

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

An ErrTranslated is a customized error type

func (ErrTranslated) Error

func (e ErrTranslated) Error() string

type ErrUnhandledType

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

An ErrUnhandledType is a customized error

func (ErrUnhandledType) Error

func (e ErrUnhandledType) Error() string

type ErrUnsupportedBitSize

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

An ErrUnsupportedBitSize is a customized error

func (ErrUnsupportedBitSize) Error

func (e ErrUnsupportedBitSize) Error() string

type Option

type Option func(*options)

An Option is a func type for applying diff options

func WithNeedEmptyValue

func WithNeedEmptyValue(c bool) Option

WithNeedEmptyValue is supposed to control whether to ignore zero value. It just happen to the element directly in structure, not including map slice array default:false, meaning ignore zero-value

func WithQueryEncoder

func WithQueryEncoder(u QueryEncoder) Option

WithQueryEncoder is supposed customized query encoder option

type QueryEncoder

type QueryEncoder interface {
	Escape(s string) string
	UnEscape(s string) (string, error)
}

A QueryEncoder is a interface implementing Escape and UnEscape method