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

    View Source
    const UnicodeVersion = "12.0.0"

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

      Variables

      This section is empty.

      Functions

      This section is empty.

      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.