emilianobovetti / elm-yajson / Yajson

Yet another JSON library inspired by OCaml Yojson.

Data structure


type Json
    = Object (List ( String, Json ))
    | Array (List Json)
    | String String
    | Number Basics.Float
    | Bool Basics.Bool
    | Null

JSON representation with Elm's union types. Strings and Json.Encode.Values can both be converted in this data structure or can be used to represent a JSON in Elm.

person : Json
person =
    Object
        [ ( "name", String "Fred" )
        , ( "age", Number 20 )
        , ( "favorite_colors"
          , Array [ String "red", String "green" ]
          )
        ]

Decoding

decoder : Json.Decode.Decoder Json

Decoder for converting values in Yajson.Json data.

Json.Decode.decodeValue decoder jsonValue

fromValue : Json.Encode.Value -> Result Json.Decode.Error Json

Shortcut for Json.Decode.decodeValue decoder.

fromValue jsonValue

fromString : String -> Result Json.Decode.Error Json

Shortcut for Json.Decode.decodeString decoder.

fromString """{ "hello": "world" }"""

Encoding

encode : Json -> Json.Encode.Value

Encode Json in Json.Encode.Value.

encode (String "hello there")

Util

member : String -> Json -> Maybe Json

Returns the value associated with the given key in a json object, or Nothing if the key isn't present in object or the json value isn't an object.

member "anything" Null == Nothing

member "a_key" (Object [ ( "a_key", String "a_value" ) ])
    == Just (String "a_value")

at : List String -> Json -> Maybe Json

Works like member, but with nested objects.

nested : Json
nested =
    """{ "foo": { "bar" : "baz" } }"""
        |> fromString
        |> Result.withDefault Null

at [ "foo", "bar" ] Null == Nothing
at [ "foo", "baz" ] nested == Nothing
at [ "foo", "bar" ] nested == Just (String "baz")

index : Basics.Int -> Json -> Maybe Json

Returns the value at index i in a json array. Indices start at 0 and negative ones count from the end, so -1 is the last element.

array : Json
array =
    Array [ Number 1, Number 2, Number 3 ]

index 0 Null == Nothing
index 0 (Array []) == Nothing
index 1 array == Just (Number 2)
index -1 array == Just (Number 3)

flatten : List Json -> List Json

Expects a list of json array and returns all their elements as a single list.

ints : List Int
ints =
    [ Array [ Number 1, Number 2.3 ]
    , Array [ Number 3, Bool False ]
    , Array [ String "hey", Number 4 ]
    ]
        |> flatten
        |> filterInt

ints == [1,3,4]

Filter

filterMember : String -> List Json -> List Json

Expects a list of json objects and returns all the fields with the given name.

joe : Json
joe =
    """{ "name": "Joe" }"""
        |> fromString
        |> Result.withDefault Null

jill : Json
jill =
    """{ "name": "Jill" }"""
        |> fromString
        |> Result.withDefault Null

names : List String
names =
    [ joe, jill ]
        |> filterMember "name"
        |> filterString

names == [ "Joe", "Jill" ]

filterAt : List String -> List Json -> List Json

Works like filterMember, but with nested objects.

joe : Json
joe =
    """
        { "name": "Joe"
        , "father": { "name": "Bob" }
        }
    """
        |> fromString
        |> Result.withDefault Null

jill : Json
jill =
    """
        { "name": "Jill"
        , "father": { "name": "Vincent" }
        }
    """
        |> fromString
        |> Result.withDefault Null

fatherNames : List String
fatherNames =
    [ joe, jill ]
        |> filterAt [ "father", "name" ]
        |> filterString

fatherNames == [ "Bob", "Vincent" ]

filterIndex : Basics.Int -> List Json -> List Json

Expects a list of json array and returns all their elements existing at the given position.

additives : Json
additives =
    """[ "red", "green", "blue" ]"""
        |> fromString
        |> Result.withDefault Null

subtractives : Json
subtractives =
    """[ "cyan", "magenta", "yellow" ]"""
        |> fromString
        |> Result.withDefault Null

lasts : List String
lasts =
    [ additives, subtractives ]
        |> filterIndex -1
        |> filterString

lasts == [ "blue", "yellow" ]

filterAssoc : List Json -> List (List ( String, Json ))

Expects a list of json objects and unwraps them.

min : Maybe Int
min =
    [ Object [ ( "key_3", Number 10 ) ]
    , Object [ ( "key_1", Number -1 ) ]
    , Object [ ( "key_2", Number 11 ) ]
    ]
        |> filterAssoc
        |> List.concatMap (List.map Tuple.second)
        |> filterInt
        |> List.minimum

min == Just -1

filterList : List Json -> List (List Json)

Expects a list of json array and unwraps them.

firsts : List Int
firsts =
    [ Array [ Number 1, Number 2 ]
    , Array [ Number 3, Number 4 ]
    , Array [ String "hey", Number 5 ]
    ]
        |> filterList
        |> List.filterMap List.head
        |> filterInt

firsts == [1,3]

filterBool : List Json -> List Basics.Bool

Expects a list of json booleans and unwraps them.

filterBool [ Bool False, Bool True ]
    == [ False, True ]

filterInt : List Json -> List Basics.Int

Expects a list of json ints and unwraps them.

filterInt [ Number 1, Number 2, Number 1.2 ]
    == [ 1, 2 ]

filterFloat : List Json -> List Basics.Float

Expects a list of json floats and unwraps them.

filterFloat [ Bool True, Number 1, Number 1.2 ]
    == [ 1, 1.2 ]

filterString : List Json -> List String

Expects a list of json strings and unwraps them.

filterString [ Number 0, String "str" ]
    == [ "str" ]

Conversion

toMaybeAssoc : Json -> Maybe (List ( String, Json ))

Extracts object representation from a Json and wraps it in a Maybe. If the json isn't an object returns Nothing.

toMaybeAssoc Null == Nothing

toMaybeAssoc (Object [ ( "key", String "value" ) ])
    == Just [ ( "key", String "value" ) ]

toAssoc : Json -> List ( String, Json )

Extracts object representation from a Json. If the json value isn't an object returns an empty list.

toAssoc Null == []

toAssoc (Object [ ( "key", String "value" ) ])
    == [ ( "key", String "value" ) ]

toMaybeList : Json -> Maybe (List Json)

Extracts array representation from a Json and wraps it in a Maybe. If the json isn't an array returns Nothing.

toMaybeList Null == Nothing

toMaybeList (Array [ Number 1, Number 2 ])
    == Just [ Number 1, Number 2 ]

toList : Json -> List Json

Extracts array representation from a Json. If the json value isn't an array returns an empty list.

toList Null == []

toList (Array [ Number 1, Number 2 ])
    == [ Number 1, Number 2 ]

toString : Json -> Maybe String

Extracts a string from a json, returns Nothing if the value doesn't contain a string.

toString Null == Nothing
toString (String "hey") == Just "hey"

toFloat : Json -> Maybe Basics.Float

Extracts a float from a json, returns Nothing if the value doesn't contain a float.

toFloat Null == Nothing
toFloat (Number 1) == Just 1

toInt : Json -> Maybe Basics.Int

Extracts an int from a json, returns Nothing if the value doesn't contain an int.

toInt (Number 0.1) == Nothing
toInt (Number 1) == Just 1

toBool : Json -> Maybe Basics.Bool

Extracts a boolean from a json, returns Nothing if the value doesn't contain a boolean.

toBool Null == Nothing
toBool (Bool False) == Just False