Safe Haskell | None |
---|---|
Language | Haskell2010 |
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".
Synopsis
- data Reference
- makeReference :: Text -> Reference
- makeLiteral :: Text -> Reference
- isValid :: Reference -> Bool
- getError :: Reference -> Text
- getComponents :: Reference -> [Text]
- getRawPath :: Reference -> Text
Documentation
data record for the Reference type.
makeReference :: Text -> Reference Source #
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 Source #
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 Source #
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 Source #
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] Source #
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 Source #
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").