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 تتيح لك تحديد كيفية تمثيل null في برنامجك، إذ تتطلب قيمة عشوائية كوسيط (ربما () أو Nothing أو أي شيء مناسب لبرنامجك).

دمج المُفكِّكات

يعرّف 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، تُستخدم لتمثيل المعالم الجغرافية مثل المواقع أو المسارات أو المناطق، محدَّدة بإحداثيات جغرافية ثنائية أو ثلاثية الأبعاد، إلى جانب خصائص أخرى.

كائن Geometry

كائن Geometry في 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]
  ]
}

يمكن تمثيل كائن Geometry في 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 ...

كائن Feature

يمثّل كائن Feature في GeoJSON شيئًا محدودًا مكانيًا: له حقل type بالقيمة "Feature"، وحقل geometry يحتوي على كائن Geometry أو null، وحقل properties يحتوي على كائن JSON عشوائي أو null، وحقل اختياري 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، الذي يمكن أن يكون كائن 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 التوقيع نفسه، لكن سلوكهما مختلف، لأن نتيجة OK Nothing من Decode.nullable لن تأتي إلا من قيمة 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، وإما إرساله إلى JavaScript مباشرةً عبر منفذ.

أصبحنا جاهزين لتحليل كائنات Feature:

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

تتيح المُرمِّزات كتابة JSON صالح من قيم Elm باستخدام الدالة Encode.encode : Int -> Value -> String. يحدد الوسيط الأول مقدار الإزاحة في النتيجة النهائية، والوسيط الثاني هو قيمة 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.