GitHup API

JSON

JSON

JSON（JavaScript Object Notation）是一種人類可讀的資料與檔案格式，常用來交換資料，特別是網頁應用程式。因此，它在 Elm 語言中占有特別的地位也就不令人意外了。

Elm 提供了核心模組Json.Decode和Json.Encode來解析與寫入 JSON 資料。JSON 解碼器是一種_宣告_預期資料型態，以及資料應該對應到哪種資料結構的方式。

我們先從這些模組匯入一些別名和型別：

import Json.Decode as Decode exposing (Decoder, Error)
import Json.Encode as Encode exposing (Value)

使用 Decode.decodeString : Decoder a -> String -> Result Error a，搭配一個解碼器和一段 JSON 字串，如果該字串符合解碼器的規格就會成功，否則就會失敗。定義解碼器時，你無法檢視原始的 JSON 資料，這對來自命令式語言的人來說可能會覺得不太習慣。

基本資料型態解碼器

JSON 只有少數幾種核心資料型態：

• 字串：以雙引號編碼，例如"hello world"
• 布林：true或false
• 數字：例如34或0.12
• Null：沒有資料，也就是null

這些型態各自對應一個Decode函式：

Decode.decodeString Decode.string """\"hello\""""
    --> Ok "hello"

Decode.decodeString Decode.string """null"""
    --> Err ...

Decode.decodeString Decode.bool """true"""
    --> Ok True

Decode.decodeString Decode.bool """0"""
    --> Err ...

Decode.decodeString Decode.int """12"""
    --> Ok 12

Decode.decodeString Decode.float """3.14"""
    --> Ok 3.14

Decode.decodeString (Decode.null AnyValue) """null"""
    --> Ok AnyValue

Decode.decodeString (Decode.null AnyValue) """true"""
    --> Err ...

注意，Decode.null要求你傳入一個任意的值作為引數（可能是()、Nothing，或任何適合你程式的東西），讓你決定要在程式中如何表示null。

組合解碼器

JSON 也定義了兩種用來收集核心資料型態的資料結構：

• 陣列：其他資料型態的集合[0, null, "none", []]
• 物件：鍵值對的集合{"id": 1, "is_admin": false, "more_info": {}}

Decode也提供了用來解碼這些結構的函式：

Decode.decodeString (Decode.list Decode.int) """[1, 2, 3]"""
    --> Ok [1, 2, 3]

Decode.decodeString (Decode.list Decode.int) """[1, 2, 3, "not an int"]"""
    --> Err ...

Decode.decodeString (Decode.dict Decode.int) """{ "key1": 17, "key2": 71 }"""
    --> Ok (Dict.fromList [("key1", 17), ("key2", 71)])

Decode.decodeString (Decode.dict Decode.int) """{ "key1": 17, "key2": "seventy-one" }"""
    --> Err ...

這些函式Decode.list : Decoder a -> Decoder (List a)和Decode.dict : Decoder a -> Decoder (Dict String a)都接受一個解碼器作為引數，這個解碼器會用來解碼資料結構中的每一個元素。如果作為引數的解碼器無法解碼陣列或物件值中的任何一個元素，整個解碼器就會失敗，這是常見的模式。

把簡單的解碼器組合成更複雜的解碼器，就是這項技術的核心概念。我們會透過一個範例，再介紹幾個函式，讓你可以建構任意複雜、貼近真實世界的資料解碼器。

GeoJSON

為了練習組合基本解碼器來解析複雜的 JSON 資料，我們來建立能解析（一部分）GeoJSON 資料的解碼器吧。GeoJSON 是一種以 JSON 為基礎的專門資料格式，用來表示地理特徵，例如位置、路徑或區域，並以 2D 或 3D 地理座標加上其他屬性來描述。

幾何物件

GeoJSON 的幾何物件是一個物件，裡面有一個值為字串的type欄位（共有 7 種可能的型態值），以及一個存放地理座標的coordinates欄位（座標收集成什麼結構取決於型態）。例如，

{
  "type": "Point",
  "coordinates": [127.831, 26.461]
}

或是

{
  "type": "LineString",
  "coordinates": [
    [127.831, 26.461],
    [127.829, 26.465],
    [127.829, 26.469],
    [127.83, 26.47]
  ]
}

幾何物件在 Elm 中可以用以下型別來表示

type Geometry
  = Point (List Float)
  | LineString (List (List Float))
  | ...

要探查某個欄位的值，我們可以使用Decode.field : String -> Decoder a -> Decoder a，它會解碼物件中特定鍵的值。

decodePointCoordinates : Decoder (List Float)
decodePointCoordinates =
    Decode.field "coordinates" (Decode.list Decode.float)

decodeLineStringCoordinates : Decoder (List (List Float))
decodeLineStringCoordinates =
    Decode.field "coordinates" (Decode.list (Decode.list Decode.float))

要轉換解碼器成功解析出來的值，我們可以使用Decode.map : (a -> value) -> Decoder a -> Decoder value，或者它的其他同類函式，從Decode.map2 (a -> b -> value) -> Decoder a -> Decoder b -> Decoder value到Decode.map8。

在這個例子中，我們想根據type欄位的值來決定要用哪一個座標解碼器，這正是Decode.andThen : (a -> Decoder b) -> Decoder a -> Decoder b以及它的好夥伴Decode.succeed : a -> Decoder a和Decode.fail : String -> Decoder a最適合的工作。

decodeGeometry : Decoder Geometry
decodeGeometry =
    Decode.field "type" Decode.string
        |> Decode.andThen
            (\value ->
                case value of
                    "Point" ->
                        decodePointCoordinates |> Decode.map Point

                    "LineString" ->
                        decodeLineStringCoordinates |> Decode.map LineString

                    _ ->
                        Decode.fail "Geometry not implemented yet, or invalid type value"
            )

到這裡請注意，我們也可以用Decode.andThen來驗證座標（檢查座標是否成對或成三出現，以及檢查座標值在地理上是否合理）。

Decode.decodeString decodeGeometry """{"type": "Point", "coordinates": [127.831, 26.461]}"""
    --> Ok (Point [127.831, 26.461])

Decode.decodeString decodeGeometry """{"type": "LineString", "coordinates": [127.831, 26.461]}"""
    --> Err ...

特徵物件

GeoJSON 的特徵物件代表某個在空間上有範圍的東西：它有一個值為"Feature"的type欄位、一個可以是幾何物件或null的geometry欄位、一個可以是任意 JSON 物件或null的properties欄位，以及一個選用的id欄位，其值可以是 JSON 字串或數字。

{
  "type": "Feature",
  "geometry": null,
  "properties": null
}

或是

{
  "type": "Feature",
  "id": "0157",
  "geometry": {
    "type": "Point",
    "coordinates": [127.831, 26.461]
  },
  "properties": {
    "country": "Japan"
  }
}

我們先來處理id欄位。如果它存在，就必須能容納字串或數字，所以我們可以為這個值另外定義一個自訂型別，或是乾脆一律把它存成字串。

要在兩個可能的解碼器之間做選擇，可以使用Decode.oneOf : List (Decoder a) -> Decoder a。

decodeFeatureId : Decoder String
decodeFeatureId =
    Decode.oneOf
        [ Decode.string
        , Decode.int |> Decode.map String.fromInt
        , Decode.float |> Decode.map String.fromFloat
        ]
        |> Decode.field "id"

Decode.decodeString decodeFeatureId """{"id": "seventeen"}"""
    --> Ok "seventeen"

Decode.decodeString decodeFeatureId """{"id": 17}"""
    --> Ok "17"

Decode.decodeString decodeFeatureId """{"type": "Point"}"""
    --> Er ...

要表達這個欄位是選用的，我們可以用同樣的技巧

decodeMaybeFeatureId : Decoder (Maybe String)
decodeMaybeFeatureId =
    Decode.oneOf
        [ decodeFeatureId |> Decode.map Just
        , Decode.succeed Nothing
        ]

不過我們也可以改用Decode.maybe : Decoder a -> Decoder (Maybe a)

decodeMaybeFeatureId : Decoder (Maybe String)
decodeMaybeFeatureId =
    Decode.maybe decodeFeatureId

Decode.decodeString decodeMaybeFeatureId """{"id": 17}"""
    --> Ok (Just "17")

Decode.decodeString decodeMaybeFeatureId """{"type": "Point"}"""
    --> Ok Nothing

注意，decodeMaybeFeatureId（或是任何用Decode.maybe包起來的解碼器）永遠都會成功，因為它總是可以退回到Ok Nothing，不過使用它的解碼器本身仍然可能失敗

Decode.decodeString (Decode.list decodeMaybeFeatureId) """{"id": 17}"""
    --> Err ...

接下來，我們來看geometry欄位，它可以是幾何物件，也可以是null。我們可以再次使用Decode.oneOf，但有個更好的選擇：Decode.nullable : Decoder a -> Decoder (Maybe a)。

decodeFeatureGeometry : Decoder (Maybe Geometry)
decodeFeatureGeometry =
    Decode.nullable decodeGeometry
        |> Decode.field "geometry"

Decode.decodeString decodeFeatureGeometry """{"geometry": {"type": "Point", "coordinates": [127.831, 26.461]}}"""
    --> Ok (Just (Point [127.831, 26.461]))

Decode.decodeString decodeFeatureGeometry """{"geometry": null}"""
    --> Ok Nothing

Decode.decodeString decodeFeatureGeometry """{"geometry": {}}"""
    --> Err ...

Decode.maybe和Decode.nullable的型別簽名相同，但行為不同，因為Decode.nullable的OK Nothing結果只會來自特定的 JSON 值null。

最後，properties欄位可以包含任意的 JSON 物件或null，這就交給Decode.value : Decoder Value來處理。

decodeProperties : Decoder (Maybe (Dict String Value))
decodeProperties =
    Decode.nullable (Decode.dict Decode.value)
        |> Decode.field "properties"


Decode.decodeString decodeProperties """{"properties": null}"""
    --> Ok Nothing

Decode.decodeString decodeProperties """{"properties": {"country": "Japan"}}"""
    --> Ok (Just (Dict.fromList [("country", <internals>)]))

Decode.decodeString decodeProperties """{"properties": 17}"""
    --> Err ...

注意，Value是一種不透明型別，意思是你不容易直接探查它的內容。要使用它，你可以為它寫一個解碼器，再用Decode.decodeValue : Decoder a -> Value -> Result Error a來執行，或是透過 port 直接把它送到 JavaScript。

我們已經準備好要解析特徵物件了：

type alias Feature =
    { id : Maybe String
    , geometry : Maybe Geometry
    , properties : Maybe (Dict String Value)
    }

decodeFeature : Decoder Feature
decodeFeature =
    Decode.field "type" Decode.string
        |> Decode.andThen
            (\value ->
                if value /= "Feature" then
                    Decode.fail "not a Feature"

                else
                    Decode.map3 Feature
                        decodeMaybeFeatureId
                        decodeFeatureGeometry
                        decodeProperties
            )

Decode.decodeString decodeFeature """{"type": "Feature", "geometry": null, "properties": null}"""
    --> Ok { geometry = Nothing, id = Nothing, properties = Nothing }

"""
{
  "type": "Feature",
  "id": "0157",
  "geometry": {
    "type": "Point",
    "coordinates": [127.831, 26.461]
  },
  "properties": {
    "country": "Japan"
  }
}
"""
  |> Decode.decodeString decodeFeature
    --> Ok { geometry = Just (Point [127.831,26.461]), id = Just "0157", properties = Just (Dict.fromList [("country",<internals>)]) }

JSON 編碼器

編碼器讓你能用Encode.encode : Int -> Value -> String函式，把 Elm 的值寫成有效的 JSON。第一個引數指定最終結果的縮排量，第二個引數則是要寫入的 JSON 值。

一個Value可以從Decode.value取得，也可以由其中一個編碼器產生：

Encode.encode 0 (Encode.string "hello")
    --> "hello"

Encode.encode 0 (Encode.bool True)
    --> "true"

Encode.encode 0 (Encode.int 12)
    --> "12"

Encode.encode 0 (Encode.float 3.14)
    --> "3.14"

Encode.encode 0 Encode.null
    --> "null"

Encode.encode 0 (Encode.list Encode.int [1, 2, 3])
    --> "[1,2,3]"

Encode.encode 4 (Encode.list Encode.int [1, 2, 3])
    --> "[\n    1,\n    2,\n    3\n]"

Encode.encode 0 (Encode.dict String.toLower Encode.int (Dict.fromList [("KEY1", 17), ("KEY2", 71)]))
    --> "{\"key1\":17,\"key2\":71}"

Encode.encode 4 (Encode.dict String.toLower Encode.int (Dict.fromList [("KEY1", 17), ("KEY2", 71)]))
    --> "{\n    \"key1\": 17,\n    \"key2\": 71\n}"

也可以用Encode.object : List ( String, Value ) -> Value

Encode.object
    [ ( "key1", Encode.int 17 )
    , ( "key2", Encode.int 71 )
    ]
    |> Encode.encode 0
    --> "{\"key1\":17,\"key2\":71}"

我們來為前面定義的 GeoJSON 解碼器定義編碼器吧

encodeGeometry : Geometry -> Value
encodeGeometry geometry =
    case geometry of
        Point coord ->
            Encode.object
                [ ( "type", Encode.string "Point" )
                , ( "coordinates", Encode.list Encode.float coord )
                ]

        LineString coord ->
            Encode.object
                [ ( "type", Encode.string "LineString" )
                , ( "coordinates", Encode.list (Encode.list Encode.float) coord )
                ]

encodeFeature : Feature -> Value
encodeFeature feature =
    let
        maybeId =
            case feature.id of
                Nothing ->
                    []

                Just id ->
                    [ ( "id", Encode.string id ) ]
    in
    Encode.object
        (maybeId
            ++ [ ( "type", Encode.string "Feature" )
               , ( "geometry"
                 , case feature.geometry of
                    Nothing ->
                        Encode.null

                    Just geometry ->
                        encodeGeometry geometry
                 )
               , ( "properties"
                 , case feature.properties of
                    Nothing ->
                        Encode.null

                    Just dict ->
                        Encode.dict identity identity dict
                 )
               ]
        )

一般來說，測試解碼器與編碼器是否成對的好方法，就是檢查elmValue |> encoder |> decoder == elmValue。