LaunchDarkly.Server.Reference

Reference is an attribute name or path expression identifying a value within a Context.

This type is mainly intended to be used internally by LaunchDarkly SDK and service code, where efficiency is a major concern so it's desirable to do any parsing or preprocessing just once. Applications are unlikely to need to use the Reference type directly.

It can be used to retrieve a value with getValueForReference or to identify an attribute or nested value that should be considered private.

Parsing and validation are done at the time that the Reference is constructed. If a Reference instance was created from an invalid string, it is considered invalid. The error can be inspected with getError.

Syntax

The string representation of an attribute reference in LaunchDarkly JSON data uses the following syntax:

If the first character is not a slash, the string is interpreted literally as an attribute name. An attribute name can contain any characters, but must not be empty.

If the first character is a slash, the string is interpreted as a slash-delimited path where the first path component is an attribute name, and each subsequent path component is the name of a property in a JSON object. Any instances of the characters "/" or "~" in a path component are escaped as "~1" or "~0" respectively. This syntax deliberately resembles JSON Pointer, but no JSON Pointer behaviors other than those mentioned here are supported.

Examples

Suppose there is a context whose JSON implementation looks like this:

{ "kind": "user", "key": "value1", "address": { "street": { "line1": "value2", "line2": "value3" }, "city": "value4" }, "good/bad": "value5" }

The attribute references "key" and "/key" would both point to "value1".

The attribute reference "addressstreet/line1" would point to "value2".

The attribute references "goodbad" and "good~1bad" would both point to "value5".

Documentation

data Reference

data record for the Reference type.

Instances

ToJSON Reference

Defined in LaunchDarkly.Server.Reference

Methods

toJSON :: Reference -> Value

toEncoding :: Reference -> Encoding

toJSONList :: [Reference] -> Value

toEncodingList :: [Reference] -> Encoding

omitField :: Reference -> Bool

Show Reference

Defined in LaunchDarkly.Server.Reference

Methods

showsPrec :: Int -> Reference -> ShowS

show :: Reference -> String

showList :: [Reference] -> ShowS

Eq Reference

Defined in LaunchDarkly.Server.Reference

Methods

(==) :: Reference -> Reference -> Bool

(/=) :: Reference -> Reference -> Bool

Ord Reference

Defined in LaunchDarkly.Server.Reference

Methods

compare :: Reference -> Reference -> Ordering

(<) :: Reference -> Reference -> Bool

(<=) :: Reference -> Reference -> Bool

(>) :: Reference -> Reference -> Bool

(>=) :: Reference -> Reference -> Bool

max :: Reference -> Reference -> Reference

min :: Reference -> Reference -> Reference

makeReference :: Text -> Reference

Creates a Reference from a string. For the supported syntax and examples, see comments on the LaunchDarkly.Server.Reference module.

This function always returns a Reference that preserves the original string, even if validation fails, so that accessing getRawPath (or serializing the Reference to JSON) will produce the original string. If validation fails, getError will return an error and any SDK method that takes this Reference as a parameter will consider it invalid.

makeLiteral :: Text -> Reference

makeLiteral is similar to makeReference except that it always interprets the string as a literal attribute name, never as a slash-delimited path expression. There is no escaping or unescaping, even if the name contains literal / or ~ characters. Since an attribute name can contain any characters, this method always returns a valid Reference unless the name is empty.

For example: makeLiteral "name" is exactly equivalent to makeReference "name". makeLiteral "a/b" is exactly equivalent to makeReference "a/b" (since the syntax used by makeReference treats the whole string as a literal as long as it does not start with a slash), or to makeReference "/a~1b".

isValid :: Reference -> Bool

Returns True for a valid Reference; False otherwise.

A Reference is invalid if the input string is empty, or starts with a slash but is not a valid slash-delimited path, or starts with a slash and contains an invalid escape sequence.

Otherwise, the Reference is valid, but that does not guarantee that such an attribute exists in any given Context. For instance, makeReference "name" is a valid Reference, but a specific Context might or might not have a name.

See comments on the LaunchDarkly.Server.Reference module for more details of the attribute reference syntax.

getError :: Reference -> Text

Returns an empty string for a valid Reference, or a Text error description for an invalid Reference.

See comments on the LaunchDarkly.Server.Reference module for more details of the attribute reference syntax.

getComponents :: Reference -> [Text]

Retrieves path components from the attribute reference.

Invalid references will return an empty list.

makeReference "" & getComponents     -- returns []
makeReference "a" & getComponents    -- returns ["a"]
makeReference "/a/b" & getComponents -- returns ["a", "b"]

getRawPath :: Reference -> Text

Returns the attribute reference as a string, in the same format provided to makeReference.

If the Reference was created with makeReference, this value is identical to the original string. If it was created with makeLiteral, the value may be different due to unescaping (for instance, an attribute whose name is "/a" would be represented as "~1a").