Next

.github/workflows/test.yml

@@ -21,3 +21,4 @@ jobs:
       - run: gleam deps download
       - run: gleam test
       - run: gleam format --check src test
+      - run: gleam run -m scripts/embed_examples -- --check README.md

.hooks/.gitignore

@@ -0,0 +1 @@
+setup_env

.hooks/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+[ -f ./.hooks/setup_env ] && source ./.hooks/setup_env
+gleam run -m scripts/embed_examples -- README.md
+git add README.md

.hooks/pre-push

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+[ -f ./.hooks/setup_env ] && source ./.hooks/setup_env
+gleam run -m scripts/embed_examples -- --check README.md

CONTRIBUTING.md

@@ -5,39 +5,45 @@ Thank you for your interest in contributing to GleoJSON! We welcome contribution
 ## Getting Started
 
 1. Fork the repository on GitHub.
-2. Clone your fork locally:
+1. Clone your fork locally:
    ```
    git clone https://github.com/guria/gleojson.git
    cd gleojson
    ```
-3. Set up your development environment with Gleam. If you haven't installed Gleam yet, follow the [official installation guide](https://gleam.run/getting-started/index.html).
+1. Set up your development environment with Gleam. If you haven't installed Gleam yet, follow the [official installation guide](https://gleam.run/getting-started/index.html).
+1. Setup git hooks with `git config core.hooksPath .hooks` and create `.hooks/setup_env` script if your Gleam executable provided by a version manager like `asdf`.
 
 ## Making Changes
 
 1. Create a new branch for your feature or bug fix:
    ```
    git checkout -b your-feature-branch
    ```
-2. Make your changes in the relevant files under the `src/` directory.
-3. Add or update tests as necessary in the `test/` directory.
-4. Run the tests to ensure your changes don't break existing functionality:
+1. Make your changes in the relevant files under the `src/` directory.
+1. Add or update tests as necessary in the `test/` directory.
+1. Run the tests to ensure your changes don't break existing functionality:
    ```
    gleam test
    ```
-5. Update the documentation if your changes affect the public API or user-facing features.
+1. Update the documentation if your changes affect the public API or user-facing features.
+1. Run `gleam run -m scripts/embed_examples -- README.md` to update usage example embed into README.md.
 
 ## Submitting Changes
 
 1. Commit your changes with a clear and descriptive commit message:
+
    ```
-   git commit -am "Add a brief description of your changes"
+   git commit -am -s "Add a brief description of your changes"
    ```
-2. Push your branch to your fork on GitHub:
+
+   By using the `-s` option, you are signing off your commit, which certifies that you accept the Developer Certificate of Origin (DCO) as defined in this document.
+
+1. Push your branch to your fork on GitHub:
    ```
    git push origin your-feature-branch
    ```
-3. Open a pull request against the main repository's `main` branch.
-4. In your pull request description, explain the changes you've made and why they're necessary.
+1. Open a pull request against the main repository's `main` branch.
+1. In your pull request description, explain the changes you've made and why they're necessary.
 
 ## Code Style and Standards
 
@@ -49,7 +55,7 @@ Thank you for your interest in contributing to GleoJSON! We welcome contribution
 If you find a bug or have a suggestion for improvement:
 
 1. Check the [GitHub Issues](https://github.com/guria/gleojson/issues) to see if it has already been reported.
-2. If not, open a new issue, providing as much detail as possible about the problem or suggestion.
+1. If not, open a new issue, providing as much detail as possible about the problem or suggestion.
 
 ## Community and Communication
 
@@ -66,6 +72,24 @@ Thank you for contributing to GleoJSON!
 
 By making a contribution to this project, I certify that:
 
-1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
-
-2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
+(a) The contribution was created in whole or in part by me and I
+have the right to submit it under the open source license
+indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+of my knowledge, is covered under an appropriate open source
+license and I have the right under that license to submit that
+work with modifications, whether created in whole or in part
+by me, under the same open source license (unless I am
+permitted to submit under a different license), as indicated
+in the file; or
+
+(c) The contribution was provided directly to me by some other
+person who certified (a), (b) or (c) and I have not modified
+it.
+
+(d) I understand and agree that this project and the contribution
+are public and that a record of the contribution (including all
+personal information I submit with it, including my sign-off) is
+maintained indefinitely and may be redistributed consistent with
+this project or the open source license(s) involved.

README.md

@@ -3,9 +3,15 @@
 [![Package Version](https://img.shields.io/hexpm/v/gleojson)](https://hex.pm/packages/gleojson)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gleojson/)
 
-**gleojson** is a comprehensive GeoJSON parsing and encoding library for Gleam, following the [RFC 7946](https://tools.ietf.org/html/rfc7946) specification. It provides robust types and utility functions to seamlessly encode and decode GeoJSON objects such as Points, LineStrings, Polygons, and more.
+**gleojson** is a comprehensive GeoJSON parsing and encoding library for Gleam, following the [RFC 7946](https://tools.ietf.org/html/rfc7946) specification.
 
-**Note:** This package is currently in development and has not reached version 1.0.0 yet. The API is considered unstable and may undergo breaking changes in future releases. Please use with caution in production environments and expect potential updates that might require code changes.
+GeoJSON is a format for encoding a variety of geographic data structures.
+It supports geometry types such as Point, LineString, Polygon, and others, as well as more complex types like Feature and FeatureCollection.
+GeoJSON is widely used in mapping applications and geographic information systems (GIS).
+
+**Note:** This package is currently in development and has not reached version 1.0.0 yet.
+The API is considered unstable and may undergo breaking changes in future releases.
+Please use with caution in production environments and expect potential updates that might require code changes.
 
 ## Features
 
@@ -38,28 +44,109 @@ gleam add gleojson
 
 Here's a basic example of how to use gleojson:
 
-```gleam
-import gleojson
+```gleam:./test/examples/encode.gleam
 import gleam/json
 import gleam/option
-import gleam/io
+import gleojson
 
 pub fn main() {
   // Create a Point geometry
-  let point = gleojson.Point(gleojson.position_2d(lon: 125.6, lat: 10.1))
-
+  gleojson.Point(gleojson.new_position_2d(lon: 125.6, lat: 10.1))
+  |> option.Some
   // Create a Feature with the Point geometry
-  let feature = gleojson.Feature(
-    geometry: option.Some(point),
+  |> gleojson.Feature(
     properties: option.None,
-    id: option.Some(gleojson.StringId("example-point"))
+    id: option.Some(gleojson.StringId("example-point")),
   )
-
   // Encode the Feature to GeoJSON
-  let encoded = gleojson.encode_geojson(feature, gleojson.properties_null_encoder)
+  |> gleojson.GeoFeature
+  |> gleojson.encode_geojson(fn(_) { json.null() })
+  |> json.to_string
+}
+```
+
+Decoding GeoJSON objects is also straightforward:
+
+```gleam:./test/examples/decode.gleam
+import decode/zero
+import gleam/bool
+import gleam/float
+import gleam/int
+import gleam/io
+import gleam/json
+import gleam/option
+import gleojson
+
+// Define custom properties type for your features
+pub type ParkProperties {
+  ParkProperties(
+    name: String,
+    area_sq_km: Float,
+    year_established: Int,
+    is_protected: Bool,
+  )
+}
 
-  // Print the encoded GeoJSON
-  io.println(json.to_string(encoded))
+// Define decoder for your custom properties
+fn park_properties_decoder() {
+  use name <- zero.field("name", zero.string)
+  use area_sq_km <- zero.field("area_sq_km", zero.float)
+  use year_established <- zero.field("year_established", zero.int)
+  use is_protected <- zero.field("is_protected", zero.bool)
+  ParkProperties(name:, area_sq_km:, year_established:, is_protected:)
+  |> zero.success
+}
+
+pub fn main() {
+  // Example GeoJSON string representing a national park
+  let json_string =
+    "{
+    \"type\": \"Feature\",
+    \"geometry\": {
+      \"type\": \"Point\",
+      \"coordinates\": [-119.5383, 37.8651]
+    },
+    \"properties\": {
+      \"name\": \"Yosemite National Park\",
+      \"area_sq_km\": 3029.87,
+      \"year_established\": 1890,
+      \"is_protected\": true
+    },
+    \"id\": \"yosemite\"
+  }"
+
+  // Decode the JSON string into a GeoJSON object
+  let decoded =
+    json.decode(
+      from: json_string,
+      using: zero.run(_, gleojson.geojson_decoder(park_properties_decoder())),
+    )
+
+  // Handle the decoded result
+  case decoded {
+    Ok(geojson) -> {
+      case geojson {
+        gleojson.GeoFeature(feature) -> {
+          case feature.properties {
+            option.Some(ParkProperties(name, area, year, is_protected)) -> {
+              io.println(
+                "Decoded " <> name <> ", established in " <> int.to_string(year),
+              )
+              io.println(
+                "Area: "
+                <> float.to_string(area)
+                <> " sq km, Protected: "
+                <> bool.to_string(is_protected),
+              )
+            }
+            option.None -> io.println("Feature has no properties")
+          }
+        }
+        _ -> io.println("Decoded a different type of GeoJSON object")
+      }
+    }
+    Error(_error) -> io.println("Failed to decode")
+  }
 }
 ```
 
@@ -82,4 +169,4 @@ Contributions to gleojson are welcome! Please feel free to submit a Pull Request
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
-Please see the [NOTICE](NOTICE) file for information about third party components and the use of AI assistance in this project.
+Please see the [NOTICE](NOTICE) file for information about third party components and the use of AI assistance in this project.

gleam.toml

@@ -4,12 +4,17 @@ version = "0.3.0"
 description = "A Gleam library for encoding and decoding GeoJSON"
 licences = ["MIT"]
 repository = { type = "github", user = "guria", repo = "gleojson" }
-links = [{ title = "RFC7946", href = "https://datatracker.ietf.org/doc/html/rfc7946" }]
+links = [
+    { title = "RFC7946", href = "https://datatracker.ietf.org/doc/html/rfc7946" },
+]
 
 [dependencies]
 gleam_stdlib = ">= 0.34.0 and < 2.0.0"
 gleam_json = ">= 2.0.0 and < 3.0.0"
+decode = ">= 0.3.0 and < 1.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"
 birdie = ">= 1.2.3 and < 2.0.0"
+argv = ">= 1.0.2 and < 2.0.0"
+simplifile = ">= 2.2.0 and < 3.0.0"

manifest.toml

@@ -4,12 +4,13 @@
 packages = [
   { name = "argv", version = "1.0.2", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "BA1FF0929525DEBA1CE67256E5ADF77A7CDDFE729E3E3F57A5BDCAA031DED09D" },
   { name = "birdie", version = "1.2.3", build_tools = ["gleam"], requirements = ["argv", "edit_distance", "filepath", "glance", "gleam_community_ansi", "gleam_erlang", "gleam_stdlib", "justin", "rank", "simplifile", "trie_again"], otp_app = "birdie", source = "hex", outer_checksum = "AE1207210E9CC8F4170BCE3FB3C23932F314C352C3FD1BCEA44CF4BF8CF60F93" },
+  { name = "decode", version = "0.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "decode", source = "hex", outer_checksum = "EE9B979C0D8A5E058E2519EC0EE9CA4C7CEE15B12997BFF50492636CDC53D0C7" },
   { name = "edit_distance", version = "2.0.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "edit_distance", source = "hex", outer_checksum = "A1E485C69A70210223E46E63985FA1008B8B2DDA9848B7897469171B29020C05" },
   { name = "filepath", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "EFB6FF65C98B2A16378ABC3EE2B14124168C0CE5201553DE652E2644DCFDB594" },
   { name = "glance", version = "0.11.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "glexer"], otp_app = "glance", source = "hex", outer_checksum = "8F3314D27773B7C3B9FB58D8C02C634290422CE531988C0394FA0DF8676B964D" },
   { name = "gleam_community_ansi", version = "1.4.1", build_tools = ["gleam"], requirements = ["gleam_community_colour", "gleam_stdlib"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "4CD513FC62523053E62ED7BAC2F36136EC17D6A8942728250A9A00A15E340E4B" },
   { name = "gleam_community_colour", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "A49A5E3AE8B637A5ACBA80ECB9B1AFE89FD3D5351FF6410A42B84F666D40D7D5" },
-  { name = "gleam_erlang", version = "0.27.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "DE468F676D71B313C6C8C5334425CFCF827837333F8AB47B64D8A6D7AA40185D" },
+  { name = "gleam_erlang", version = "0.28.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "BE551521F708DCE5CB954AFBBDF08519C1C44986521FD40753608825F48FFA9E" },
   { name = "gleam_json", version = "2.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "CB10B0E7BF44282FB25162F1A24C1A025F6B93E777CCF238C4017E4EEF2CDE97" },
   { name = "gleam_stdlib", version = "0.40.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "86606B75A600BBD05E539EB59FABC6E307EEEA7B1E5865AFB6D980A93BCB2181" },
   { name = "gleeunit", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "F7A7228925D3EE7D0813C922E062BFD6D7E9310F0BEE585D3A42F3307E3CFD13" },
@@ -21,7 +22,10 @@ packages = [
 ]
 
 [requirements]
+argv = { version = ">= 1.0.2 and < 2.0.0" }
 birdie = { version = ">= 1.2.3 and < 2.0.0" }
+decode = { version = ">= 0.3.0 and < 1.0.0" }
 gleam_json = { version = ">= 2.0.0 and < 3.0.0" }
 gleam_stdlib = { version = ">= 0.34.0 and < 2.0.0" }
 gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+simplifile = { version = ">= 2.2.0 and < 3.0.0" }