precis

Documentation

Overview

Package precis contains types and functions for the preparation, enforcement, and comparison of internationalized strings ("PRECIS") as defined in RFC 8264. It also contains several pre-defined profiles for passwords, nicknames, and usernames as defined in RFC 8265 and RFC 8266.

BE ADVISED: This package is under construction and the API may change in backwards incompatible ways and without notice.

Index

• Constants
• type Option
  • func AdditionalMapping(t ...func() transform.Transformer) Option
  • func Disallow(set runes.Set) Option
  • func FoldCase(opts ...cases.Option) Option
  • func LowerCase(opts ...cases.Option) Option
  • func Norm(f norm.Form) Option
• type Profile
  • func NewFreeform(opts ...Option) *Profile
  • func NewIdentifier(opts ...Option) *Profile
  • func NewRestrictedProfile(parent *Profile, disallow runes.Set) *Profile
  • func (p *Profile) Allowed() runes.Set
  • func (p *Profile) Append(dst, src []byte) ([]byte, error)
  • func (p *Profile) AppendCompareKey(dst, src []byte) ([]byte, error)
  • func (p *Profile) Bytes(b []byte) ([]byte, error)
  • func (p *Profile) Compare(a, b string) bool
  • func (p *Profile) CompareKey(s string) (string, error)
  • func (p *Profile) NewTransformer() *Transformer
  • func (p *Profile) String(s string) (string, error)
• type Transformer
  • func (t Transformer) Bytes(b []byte) []byte
  • func (t Transformer) Reset()
  • func (t Transformer) String(s string) string
  • func (t Transformer) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)

Constants

const UnicodeVersion = "15.0.0"

UnicodeVersion is the Unicode version from which the tables in this package are derived.

Types

type Option

type Option func(*options)

An Option is used to define the behavior and rules of a Profile.

var (
	// The IgnoreCase option causes the profile to perform a case insensitive
	// comparison during the PRECIS comparison step.
	IgnoreCase Option = ignoreCase

	// The FoldWidth option causes the profile to map non-canonical wide and
	// narrow variants to their decomposition mapping. This is useful for
	// profiles that are based on the identifier class which would otherwise
	// disallow such characters.
	FoldWidth Option = foldWidth

	// The DisallowEmpty option causes the enforcement step to return an error if
	// the resulting string would be empty.
	DisallowEmpty Option = disallowEmpty

	// The BidiRule option causes the Bidi Rule defined in RFC 5893 to be
	// applied.
	BidiRule Option = bidiRule
)

func AdditionalMapping

func AdditionalMapping(t ...func() transform.Transformer) Option

The AdditionalMapping option defines the additional mapping rule for the Profile by applying Transformer's in sequence.

func Disallow

func Disallow(set runes.Set) Option

The Disallow option further restricts a Profile's allowed characters beyond what is disallowed by the underlying string class.

func FoldCase

func FoldCase(opts ...cases.Option) Option

The FoldCase option defines a Profile's case mapping rule. Options can be provided to determine the type of case folding used.

func LowerCase

func LowerCase(opts ...cases.Option) Option

The LowerCase option defines a Profile's case mapping rule. Options can be provided to determine the type of case folding used.

func Norm

func Norm(f norm.Form) Option

The Norm option defines a Profile's normalization rule. Defaults to NFC.

type Profile

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

A Profile represents a set of rules for normalizing and validating strings in the PRECIS framework.

var (
	// Implements the Nickname profile specified in RFC 8266.
	Nickname *Profile = nickname

	// Implements the UsernameCaseMapped profile specified in RFC 8265.
	UsernameCaseMapped *Profile = usernameCaseMap

	// Implements the UsernameCasePreserved profile specified in RFC 8265.
	UsernameCasePreserved *Profile = usernameNoCaseMap

	// Implements the OpaqueString profile defined in RFC 8265 for passwords and
	// other secure labels.
	OpaqueString *Profile = opaquestring
)

func NewFreeform

func NewFreeform(opts ...Option) *Profile

NewFreeform creates a new PRECIS profile based on the Freeform string class. Profiles created from this class are suitable for use where expressiveness is prioritized over safety like passwords, and display-elements such as nicknames in a chat room.

func NewIdentifier

func NewIdentifier(opts ...Option) *Profile

NewIdentifier creates a new PRECIS profile based on the Identifier string class. Profiles created from this class are suitable for use where safety is prioritized over expressiveness like network identifiers, user accounts, chat rooms, and file names.

func NewRestrictedProfile

func NewRestrictedProfile(parent *Profile, disallow runes.Set) *Profile

NewRestrictedProfile creates a new PRECIS profile based on an existing profile. If the parent profile already had the Disallow option set, the new rule overrides the parents rule.

func (*Profile) Allowed

func (p *Profile) Allowed() runes.Set

Allowed returns a runes.Set containing every rune that is a member of the underlying profile's string class and not disallowed by any profile specific rules.

func (*Profile) Append

func (p *Profile) Append(dst, src []byte) ([]byte, error)

Append appends the result of applying p to src writing the result to dst. It returns an error if the input string is invalid.

func (*Profile) AppendCompareKey

func (p *Profile) AppendCompareKey(dst, src []byte) ([]byte, error)

AppendCompareKey appends the result of applying p to src (including any optional rules to make strings comparable or useful in a map key such as applying lowercasing) writing the result to dst. It returns an error if the input string is invalid.

func (*Profile) Bytes

func (p *Profile) Bytes(b []byte) ([]byte, error)

Bytes returns a new byte slice with the result of applying the profile to b.

func (*Profile) Compare

func (p *Profile) Compare(a, b string) bool

Compare enforces both strings, and then compares them for bit-string identity (byte-for-byte equality). If either string cannot be enforced, the comparison is false.

func (*Profile) CompareKey

func (p *Profile) CompareKey(s string) (string, error)

CompareKey returns a string that can be used for comparison, hashing, or collation.

func (*Profile) NewTransformer

func (p *Profile) NewTransformer() *Transformer

NewTransformer creates a new transform.Transformer that performs the PRECIS preparation and enforcement steps on the given UTF-8 encoded bytes.

func (*Profile) String

func (p *Profile) String(s string) (string, error)

String returns a string with the result of applying the profile to s.

type Transformer

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

Transformer implements the transform.Transformer interface.

func (Transformer) Bytes

func (t Transformer) Bytes(b []byte) []byte

Bytes returns a new byte slice with the result of applying t to b.

func (Transformer) Reset

func (t Transformer) Reset()

Reset implements the transform.Transformer interface.

func (Transformer) String

func (t Transformer) String(s string) string

String returns a string with the result of applying t to s.

func (Transformer) Transform

func (t Transformer) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)

Transform implements the transform.Transformer interface.