The Named is a wrapper around any Text that identifies the type of Text via the nameOf phantom symbol type, as well as a usage specified by the style type parameter. Use of Named should always be preferred to using a raw Text (or String).

Retrieve the nameOf type parameter (the "what am I") of a Named as a text value

Retrieve a proxy for the nameOf parameter of Named.

Retrieve a proxy for the style parameter of Named.

The SomeName data type is used to existentially hide the identification type parameter for Named objects. This is usually used when names of different types are mixed together in some container or other name-agnostic interface.

The viewSomeName function is used to project the Named object with its identification type parameter existentially recovered to a function that will consume that Named object and return some sort of result.

Some objects have (contain) an associated name that identifies or labels that object. If they do, they can declare the HasName constraint, and use its myName method to reconstitute the Named from the object.

myName can be used to extract the associated Named from an object.

The NameStyle specifies how the name itself is styled.

• The UTF8 default style is orthogonal to a normal String or Text.
• The CaseInsensitive style indicates that uppercase ASCII characters are equivalent to their lowercase form.
• The Secure style is case sensitive, but does not reveal the full contents unless the specific "secureName" accessor function is used. This is useful for storing secrets (e.g. passphrases, access tokens, etc.) that should not be fully visible in log messages and other miscellaneous output.

These styles will be described in more detail below.

The SomeNameStyle data type is used to existentially hide the style type of Named objects. This is usually used when names of different styles are mixed together in some container or other style-agnostic interface.

The viewSomeNameStyle function is used to project the Named object with its style type existentially recovered to a function that will consume that Named object and return some sort of result.

The IsText class provides similar functionality to the IsString class, but with Text sources instead of String sources. Defining an instance of this class allows the use of fromText to convert from Text to the target type (which does not necessarily need to be a Named type, and this generic class should be deprecated in favor of a generic implementation the the "text" library).

Conversion from a Named with one nameOf to a separate nameOf must be done explicitly; the recommended method is via an instance of the ConvertName class, which provides the convertName method to perform the requested conversion. If there should not be a conversion between the two Named types, no ConvertName class should be defined, and users should refrain from providing an alternative explicit function to perform this conversion.

A Named can be converted from one style to another with an instance of the ConvertNameStyle class. If no conversion should be supported, no instance should be defined. Users are highly recommended to use the convertStyle method (instead of a separate manual conversion function) to ensure proper conversions are performed.

A general class that can be used to extract the Text back out of a name. This should be the preferred method of obtaining the raw Text, and should be used carefully as all of the protections provided by this module are no longer available for that raw Text. In addition, no instance of this class is provided where the name should not be extractable, and this method may extract a modified form of the text (e.g. the Secure namestyle will return a masked version of the original Text).

nameText is used to retrieve the original Text text from a Named object of the specified style. This should be the main method used to extract the Text from a Named, but it should be used carefully because the protections offered by the Named type will no longer be available for the raw Text.

The UTF8 type alias is useable as the style parameter of a Named type. The type-string form may also be used but the type alias is designed to allow abstraction from the raw type-string value.

The Name type is for the standard/most commonly used style which is orthogonal to a normal String or Text. Because this is the most frequently used form of Named, it has a type alias to shorten the usage references.

The CaseInsensitive style of Named objects will allow case-insensitive ASCII comparisons between objects. On creation, all text is converted to lowercase, so the original input case is not preserved on extraction or rendering.

The Secure style of Named objects masks the internal text on extraction or rendering to avoid leaking information. The actual internal text can be retrieved only with the explicit secureNameBypass function.

The SecureName is like Name, but its display form does not reveal the full name. The use of the nameText extractor or any of the renderers will occlude a portion of the secure name to avoid revealing it in its entirety.

The secureName accessor is used to obtain the name field from a Secure Named. This is the normal accessor for a Secure Named and will occlude a portion of the extracted name for protection. For those specific cases where the full Secure Named text is needed, the secureNameBypass accessor should be used instead.

The secureNameBypass accessor is used to obtain the raw Text from a Secure Named; this essentially BYPASSES THE SECURITY PROTECTION and should only be used in the limited cases when the raw form is absolutely needed.

The ValidNames constraint can be used to specify the list of allowed names for a parameterized name argument. For example:

foo :: ValidNames n '[ "right", "correct" ] => Name n -> a

The above allows foo to be called with a Name "right" or a Name "correct", but if it is called with any other Named nameOf parameter then a compilation error will be generated indicating "the supplied nameOf type parameter is not in the allowed Names".

All instances of this class are pre-defined by this module and the user should not need to create any instances.

The validName method is used to extract the text form of a Name for which nameOf is a member of the valid names specified by the ntl type list. It corresponds to nameText while also providing the validation of the extraction.

Returns the length of the underlying Text

Returns true if the name value is empty.