GitHup API

JSON

JSON

Το JSON (JavaScript Object Notation) είναι μια μορφή δεδομένων και αρχείων αναγνώσιμη από τον άνθρωπο, που χρησιμοποιείται συνήθως για την ανταλλαγή δεδομένων, ειδικά για εφαρμογές ιστού. Ως εκ τούτου, δεν αποτελεί έκπληξη το γεγονός ότι κατέχει ξεχωριστή θέση στη γλώσσα Elm.

Η Elm παρέχει τα βασικά modules Json.Decode και Json.Encode για την ανάλυση και τη συγγραφή δεδομένων JSON. Οι αποκωδικοποιητές JSON είναι ένας τρόπος να δηλώσεις τι τύπο δεδομένων περιμένεις και σε ποια δομή δεδομένων πρέπει να αντιστοιχιστούν τα δεδομένα.

Ας εισάγουμε μερικά aliases και τύπους από τα modules:

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 έχει έναν μικρό αριθμό βασικών τύπων δεδομένων:

• String: κωδικοποιείται με διπλά εισαγωγικά "hello world"
• Boolean: είτε true είτε false
• Number: όπως 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 ορίζει επίσης δύο δομές δεδομένων για τη συλλογή βασικών τύπων δεδομένων:

• Array: μια συλλογή άλλων τύπων δεδομένων [0, null, "none", []]
• Object: μια συλλογή ζευγών κλειδιού-τιμής {"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) περιμένουν η καθεμία έναν αποκωδικοποιητή ως όρισμα, ο οποίος αναμένεται να αποκωδικοποιήσει κάθε μεμονωμένο στοιχείο της δομής δεδομένων. Αν ο αποκωδικοποιητής-όρισμα αποτύχει να αποκωδικοποιήσει οποιοδήποτε στοιχείο μιας τιμής array ή object, ολόκληρος ο αποκωδικοποιητής αποτυγχάνει, κάτι που είναι ένα συνηθισμένο μοτίβο.

Ο συνδυασμός απλών αποκωδικοποιητών σε πιο σύνθετους είναι η βασική ιδέα της τεχνικής. Θα παρουσιάσουμε αρκετές ακόμη συναρτήσεις που μπορούν να χρησιμοποιηθούν για να χτίσεις αποκωδικοποιητές δεδομένων του πραγματικού κόσμου, οσοδήποτε σύνθετους, μέσα από ένα παράδειγμα.

GeoJSON

Για να εξασκηθείς στον συνδυασμό βασικών αποκωδικοποιητών ώστε να αναλύεις σύνθετα δεδομένα JSON, ας φτιάξουμε αποκωδικοποιητές για την ανάλυση (ενός υποσυνόλου) δεδομένων GeoJSON. Το GeoJSON είναι μια εξειδικευμένη μορφή δεδομένων βασισμένη στο JSON, που χρησιμοποιείται για την αναπαράσταση γεωγραφικών χαρακτηριστικών, όπως τοποθεσίες, διαδρομές ή περιοχές, με γεωγραφικές συντεταγμένες 2D ή 3D, μαζί με άλλες ιδιότητες.

Γεωμετρικό Αντικείμενο

Ένα Γεωμετρικό Αντικείμενο GeoJSON είναι ένα αντικείμενο που περιέχει ένα πεδίο type με τιμή συμβολοσειράς (υπάρχουν 7 πιθανές τιμές για το type) και ένα πεδίο 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 αναπαριστά κάτι με χωρικά όρια: έχει ένα πεδίο type με την τιμή "Feature", ένα πεδίο geometry με ένα Γεωμετρικό Αντικείμενο ή ένα null, ένα πεδίο properties με ένα αυθαίρετο JSON Object ή ένα 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, το οποίο μπορεί είτε να είναι ένα Γεωμετρικό Αντικείμενο είτε 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 Object ή ένα 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 μέσω ενός port.

Είμαστε έτοιμοι να αναλύσουμε Αντικείμενα Χαρακτηριστικού:

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.