package precis

Import Path
	golang.org/x/text/secure/precis (on go.dev)

Dependency Relation
	imports 11 packages, and imported by one package

Involved Source Files

	      class.go
	      context.go
	   d➜ doc.go
		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.

	      nickname.go
	      options.go
	      profile.go
	      profiles.go
	      tables13.0.0.go
	      transformer.go
	      trieval.go
Package-Level Type Names (total 14, in which 3 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Option (func)
		An Option is used to define the behavior and rules of a Profile.

		As Outputs Of (at least 5, all are exported)
			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
		As Inputs Of (at least 3, in which 2 are exported)
			func NewFreeform(opts ...Option) *Profile
			func NewIdentifier(opts ...Option) *Profile
			/* at least one unexported ... *//* at least one unexported: */
			func getOpts(o ...Option) (res options)
		As Types Of (total 4, all are exported)
			  var BidiRule
			  var DisallowEmpty
			  var FoldWidth
			  var IgnoreCase

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

		Fields (total 13, none are exported)
			/* 13 unexporteds ... *//* 13 unexporteds: */
			class *class
			options options
			options.additional []func() transform.SpanningTransformer
			options.asciiLower bool
				Enforcement options

			options.bidiRule bool
			options.cases transform.SpanningTransformer
			options.disallow runes.Set
			options.disallowEmpty bool
			options.foldWidth bool
				Preparation options

			options.ignorecase bool
				Comparison options

			options.norm transform.SpanningTransformer
			options.repeat bool
			options.width transform.SpanningTransformer
		Methods (total 8, all are exported)
			(*T) 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.

			(*T) 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.

			(*T) 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.

			(*T) Bytes(b []byte) ([]byte, error)
				Bytes returns a new byte slice with the result of applying the profile to b.

			(*T) 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.

			(*T) CompareKey(s string) (string, error)
				CompareKey returns a string that can be used for comparison, hashing, or
				collation.

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

			(*T) String(s string) (string, error)
				String returns a string with the result of applying the profile to s.

		As Outputs Of (at least 3, all are exported)
			func NewFreeform(opts ...Option) *Profile
			func NewIdentifier(opts ...Option) *Profile
			func NewRestrictedProfile(parent *Profile, disallow runes.Set) *Profile
		As Inputs Of (at least 3, in which 1 are exported)
			func NewRestrictedProfile(parent *Profile, disallow runes.Set) *Profile
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func processBytes(p *Profile, b []byte, key bool) ([]byte, error)
			func processString(p *Profile, s string, key bool) (string, error)
		As Types Of (total 8, in which 4 are exported)
			  var Nickname *Profile
			  var OpaqueString *Profile
			  var UsernameCaseMapped *Profile
			  var UsernameCasePreserved *Profile
			/* 4 unexporteds ... *//* 4 unexporteds: */
			  var nickname *Profile
			  var opaquestring *Profile
			  var usernameCaseMap *Profile
			  var usernameNoCaseMap *Profile

	 type Transformer (struct)
		Transformer implements the transform.Transformer interface.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			t transform.Transformer
		Methods (total 4, all are exported)
			( T) Bytes(b []byte) []byte
				Bytes returns a new byte slice with the result of applying t to b.

			( T) Reset()
				Reset implements the transform.Transformer interface.

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

			( T) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)
				Transform implements the transform.Transformer interface.

		Implements (at least 2, both are exported)
			 T : golang.org/x/text/transform.Transformer
			 T : vendor/golang.org/x/text/transform.Transformer
		As Outputs Of (at least one exported)
			func (*Profile).NewTransformer() *Transformer

	/* 11 unexporteds ... *//* 11 unexporteds: */
	 type buffers (struct)

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			buf [2][]byte
			next int
			src []byte
		Methods (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*T) apply(t transform.SpanningTransformer) (err error)
			(*T) enforce(p *Profile, src []byte, comparing bool) (str []byte, err error)

	 type catBitmap uint16 (basic type)

		As Types Of (total 12, none are exported)
			/* 12 unexporteds ... *//* 12 unexporteds: */
			const bArabicIndicDigit
			const bExtendedArabicIndicDigit
			const bGreek
			const bHebrew
			const bJapanese
			const bJoinEnd
			const bJoinMid
			const bJoinStart
			const bLatinSmallL
			const bMustHaveJapn
			const bVirama
			const permanent

	 type category uint8 (basic type)
		compute permutations of all properties and specialCategories.

		As Types Of (total 22, none are exported)
			/* 22 unexporteds ... *//* 22 unexporteds: */
			const arabicIndicDigit
			const extendedArabicIndicDigit
			const greek
			const greekJoinT
			const greekLowerNumeralSign
			const hebrew
			const hebrewJoinT
			const hebrewPreceding
			const japanese
			const joiningD
			const joiningL
			const joiningR
			const joiningT
			const katakanaMiddleDot
			const latinSmallL
			const middleDot
			const numCategories
			const other
			const viramaJoinT
			const viramaModifier
			const zeroWidthJoiner
			const zeroWidthNonJoiner

	 type checker (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			acceptBits catBitmap
			allowed runes.Set
			beforeBits catBitmap
			p *Profile
			termBits catBitmap
		Methods (total 3, in which 2 are exported)
			(*T) Reset()
			( T) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)
				TODO: we may get rid of this transform if transform.Chain understands
				something like a Spanner interface.

			/* one unexported ... *//* one unexported: */
			(*T) span(src []byte, atEOF bool) (n int, err error)
		Implements (at least 2, both are exported)
			*T : golang.org/x/text/transform.Transformer
			*T : vendor/golang.org/x/text/transform.Transformer

	 type class (struct)
		A class is a set of characters that match certain derived properties. The
		PRECIS framework defines two classes: The Freeform class and the Identifier
		class. The freeform class should be used for profiles where expressiveness is
		prioritized over safety such as nicknames or passwords. The identifier class
		should be used for profiles where safety is the first priority such as
		addressable network labels and usernames.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			validFrom property
		Methods (only one, which is exported)
			( T) Contains(r rune) bool
				Contains satisfies the runes.Set interface and returns whether the given rune
				is a member of the class.

		Implements (at least one exported)
			 T : golang.org/x/text/runes.Set
		As Types Of (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			  var freeform *class
			  var identifier *class

	 type derivedPropertiesTrie (struct)
		derivedPropertiesTrie. Total size: 27776 bytes (27.12 KiB). Checksum: c8bfc091c977a4c.

		Methods (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			(*T) lookup(s []byte) (v uint8, sz int)
				lookup returns the trie value for the first UTF-8 encoding in s and
				the width in bytes of this encoding. The size will be 0 if s does not
				hold enough bytes to complete the encoding. len(s) must be greater than 0.

			(*T) lookupString(s string) (v uint8, sz int)
				lookupString returns the trie value for the first UTF-8 encoding in s and
				the width in bytes of this encoding. The size will be 0 if s does not
				hold enough bytes to complete the encoding. len(s) must be greater than 0.

			(*T) lookupStringUnsafe(s string) uint8
				lookupStringUnsafe returns the trie value for the first UTF-8 encoding in s.
				s must start with a full and valid UTF-8 encoded rune.

			(*T) lookupUnsafe(s []byte) uint8
				lookupUnsafe returns the trie value for the first UTF-8 encoding in s.
				s must start with a full and valid UTF-8 encoded rune.

			(*T) lookupValue(n uint32, b byte) uint8
				lookupValue determines the type of block n and looks up the value for b.

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newDerivedPropertiesTrie(i int) *derivedPropertiesTrie
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var dpTrie *derivedPropertiesTrie

	 type entry uint8 (basic type)
		entry is the entry of a trie table
		7..6   property (unassigned, disallowed, maybe, valid)
		5..0   category

		Methods (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			( T) category() category
			( T) property() property

	 type nickAdditionalMapping (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			notStart bool
				TODO: This transformer needs to be stateless somehow…

			prevSpace bool
		Methods (total 2, both are exported)
			(*T) Reset()
			(*T) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)
		Implements (at least 2, both are exported)
			*T : golang.org/x/text/transform.Transformer
			*T : vendor/golang.org/x/text/transform.Transformer

	 type options (struct)

		Fields (total 11, none are exported)
			/* 11 unexporteds ... *//* 11 unexporteds: */
			additional []func() transform.SpanningTransformer
			asciiLower bool
				Enforcement options

			bidiRule bool
			cases transform.SpanningTransformer
			disallow runes.Set
			disallowEmpty bool
			foldWidth bool
				Preparation options

			ignorecase bool
				Comparison options

			norm transform.SpanningTransformer
			repeat bool
			width transform.SpanningTransformer
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func getOpts(o ...Option) (res options)

	 type property uint8 (basic type)

		As Types Of (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			const disallowed
			const idDisOrFreePVal
			const pValid
			const unassigned

	 type spanWrap (struct)

		Fields (only one, which is exported)
			Transformer transform.Transformer
		Methods (total 3, all are exported)
			( T) Reset()
				Reset resets the state and allows a Transformer to be reused.

			( T) Span(src []byte, atEOF bool) (n int, err error)
			( T) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)
				Transform writes to dst the transformed bytes read from src, and
				returns the number of dst bytes written and src bytes read. The
				atEOF argument tells whether src represents the last bytes of the
				input.

				Callers should always process the nDst bytes produced and account
				for the nSrc bytes consumed before considering the error err.

				A nil error means that all of the transformed bytes (whether freshly
				transformed from src or left over from previous Transform calls)
				were written to dst. A nil error can be returned regardless of
				whether atEOF is true. If err is nil then nSrc must equal len(src);
				the converse is not necessarily true.

				ErrShortDst means that dst was too short to receive all of the
				transformed bytes. ErrShortSrc means that src had insufficient data
				to complete the transformation. If both conditions apply, then
				either error may be returned. Other than the error conditions listed
				here, implementations are free to report other errors that arise.

		Implements (at least 4, all are exported)
			 T : golang.org/x/text/transform.SpanningTransformer
			 T : golang.org/x/text/transform.Transformer
			 T : vendor/golang.org/x/text/transform.SpanningTransformer
			 T : vendor/golang.org/x/text/transform.Transformer


Package-Level Functions (total 13, in which 8 are exported)

	 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(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(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(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 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(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(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 Norm(f norm.Form) Option
		The Norm option defines a Profile's normalization rule. Defaults to NFC.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func getOpts(o ...Option) (res options)
	 func init()
	 func newDerivedPropertiesTrie(i int) *derivedPropertiesTrie
	 func processBytes(p *Profile, b []byte, key bool) ([]byte, error)
	 func processString(p *Profile, s string, key bool) (string, error)
Package-Level Variables (total 29, in which 8 are exported)

	  var BidiRule Option
		The BidiRule option causes the Bidi Rule defined in RFC 5893 to be
		applied.

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

	  var FoldWidth Option
		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.

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

	  var Nickname *Profile
		Implements the Nickname profile specified in RFC 8266.

	  var OpaqueString *Profile
		Implements the OpaqueString profile defined in RFC 8265 for passwords and
		other secure labels.

	  var UsernameCaseMapped *Profile
		Implements the UsernameCaseMapped profile specified in RFC 8265.

	  var UsernameCasePreserved *Profile
		Implements the UsernameCasePreserved profile specified in RFC 8265.

	/* 21 unexporteds ... *//* 21 unexporteds: */
	  var bidiRule func(o *options)
	  var categoryTransitions []struct{keep catBitmap; set catBitmap; term catBitmap; accept catBitmap; rule func(beforeBits catBitmap) (doLookahead bool, err error)}
	  var derivedPropertiesIndex [2432]uint16
		derivedPropertiesIndex: 38 blocks, 2432 entries, 4864 bytes
		Block 0 is the zero block.

	  var derivedPropertiesValues [22912]uint8
		derivedPropertiesValues: 358 blocks, 22912 entries, 22912 bytes
		The third block is the zero block.

	  var disallowEmpty func(o *options)
	  var dpTrie *derivedPropertiesTrie
	  var errContext error
	  var errDisallowedRune error
	  var errEmptyString error
	  var foldWidth func(o *options)
	  var foldWidthT transform.SpanningTransformer
		Pre-allocate transformers when possible. In some cases this avoids allocation.

	  var freeform *class
	  var identifier *class
	  var ignoreCase func(o *options)
	  var lowerCaseT transform.SpanningTransformer
		Pre-allocate transformers when possible. In some cases this avoids allocation.

	  var mapSpaces transform.Transformer
		mapSpaces is a shared value of a runes.Map transformer.

	  var nickname *Profile
	  var opaquestring *Profile
	  var repeat func(o *options)
	  var usernameCaseMap *Profile
	  var usernameNoCaseMap *Profile
Package-Level Constants (total 43, in which 1 are exported)

	const UnicodeVersion = "13.0.0"
		UnicodeVersion is the Unicode version from which the tables in this package are derived.

	/* 42 unexporteds ... *//* 42 unexporteds: */
	const arabicIndicDigit category = 19 // rule 8
	const bArabicIndicDigit catBitmap = 2
	const bExtendedArabicIndicDigit catBitmap = 4
	const bGreek catBitmap = 256
	const bHebrew catBitmap = 512
	const bJapanese catBitmap = 1
		These bits, once set depending on the current value, are never unset.

	const bJoinEnd catBitmap = 32
	const bJoinMid catBitmap = 16
	const bJoinStart catBitmap = 8
		These bits are set on each iteration depending on the current value.

	const bLatinSmallL catBitmap = 128
	const bMustHaveJapn catBitmap = 1024
		These bits indicated which of the permanent bits need to be set at the
		end of the checks.

	const bVirama catBitmap = 64
	const catMask = 63
	const disallowed property = 64
		The order of these constants matter. A Profile may consider runes to be
		allowed either from pValid or idDisOrFreePVal.

	const extendedArabicIndicDigit category = 20 // rule 9
	const finalShift = 10
	const greek category = 8
	const greekJoinT category = 9 // Greek + JoiningT
	const greekLowerNumeralSign category = 16 // rule 4
	const hebrew category = 10
	const hebrewJoinT category = 11 // Hebrew + JoiningT
	const hebrewPreceding category = 17 // rule 5 and 6
	const idDisOrFreePVal property = 128 // disallowed for Identifier, pValid for FreeForm
		The order of these constants matter. A Profile may consider runes to be
		allowed either from pValid or idDisOrFreePVal.

	const japanese category = 12 // hirigana, katakana, han
	const joiningD category = 2
	const joiningL category = 1
		Special rune types

	const joiningR category = 4
	const joiningT category = 3
	const katakanaMiddleDot category = 18 // rule 7
	const latinSmallL category = 7 // U+006c
	const middleDot category = 15 // rule 3
		ContextJ

	const numCategories category = 21
	const other category = 0
	const permanent catBitmap = 1031
	const propMask = 192
	const propShift = 6
	const pValid property = 192
		The order of these constants matter. A Profile may consider runes to be
		allowed either from pValid or idDisOrFreePVal.

	const unassigned property = 0
		The order of these constants matter. A Profile may consider runes to be
		allowed either from pValid or idDisOrFreePVal.

	const viramaJoinT category = 6 // Virama + JoiningT
	const viramaModifier category = 5
	const zeroWidthJoiner category = 14 // rule 2
	const zeroWidthNonJoiner category = 13 // rule 1
		Special rune types associated with contextual rules defined in
		https://tools.ietf.org/html/rfc5892#appendix-A.
		ContextO

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.