{"id":16195588,"url":"https://github.com/ayys/gson","last_synced_at":"2025-07-25T16:08:54.795Z","repository":{"id":56214025,"uuid":"304781388","full_name":"ayys/gson","owner":"ayys","description":"GSON is a JSON library written in Guile","archived":false,"fork":false,"pushed_at":"2020-11-20T05:47:35.000Z","size":67,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-13T18:42:30.520Z","etag":null,"topics":["guile","json","library","parser","scheme"],"latest_commit_sha":null,"homepage":"","language":"Scheme","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-17T02:30:15.000Z","updated_at":"2023-02-11T06:14:14.000Z","dependencies_parsed_at":"2022-08-15T14:50:21.179Z","dependency_job_id":null,"html_url":"https://github.com/ayys/gson","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayys%2Fgson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayys%2Fgson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayys%2Fgson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayys%2Fgson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayys","download_url":"https://codeload.github.com/ayys/gson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247685634,"owners_count":20979085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guile","json","library","parser","scheme"],"created_at":"2024-10-10T08:28:59.237Z","updated_at":"2025-04-07T16:19:37.154Z","avatar_url":"https://github.com/ayys.png","language":"Scheme","funding_links":[],"categories":[],"sub_categories":[],"readme":"![gson logo](https://i.ibb.co/grwL3NJ/gson-header.png \"gson header\")\n\nTable of Contents\n=================\n\n   * [GSON](#gson)\n      * [Getting Started](#getting-started)\n      * [Installation](#installation)\n         * [Installing make on Debian / Ubuntu](#installing-make-on-debian--ubuntu)\n      * [Documentation](#documentation)\n         * [json-string-\u0026gt;scm](#json-string-scm)\n         * [json-port-\u0026gt;scm](#json-port-scm)\n         * [json-file-\u0026gt;scm](#json-file-scm)\n         * [scm-\u0026gt;json-string](#scm-json-string)\n         * [scm-\u0026gt;json-port](#scm-json-port)\n         * [scm-\u0026gt;json-file](#scm-json-file)\n         * [Hooks](#hooks)\n            * [Example of json-string-\u0026gt;scm with hooks](#example-of-json-string-scm-with-hooks)\n            * [object-hook](#object-hook)\n            * [list-hook](#list-hook)\n            * [number-hook](#number-hook)\n            * [string-hook](#string-hook)\n            * [boolean-hook](#boolean-hook)\n            * [nil-hook](#nil-hook)\n         * [Exception Handling](#exception-handling)\n         * [Default Conversion Format](#default-conversion-format)\n      * [License](#license)\n\n\n## Getting Started\n\nLet's get started with a very simple example. This example does not\nperform exception handling.\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n;;; Define variable code which stores a JSON string\n(define code\n  \"\n{\n    \\\"name\\\": \\\"John Doe\\\",\n    \\\"age\\\": 43,\n    \\\"address\\\": {\n        \\\"street\\\": \\\"10 Downing Street\\\",\n        \\\"city\\\": \\\"London\\\"\n    },\n    \\\"phones\\\": [\n        \\\"+44 1234567\\\",\n        \\\"+44 2345678\\\"\n    ]\n}\")\n\n;;; Print the scheme representation of above JSON\n(display(json-string-\u003escm code))\n(newline)\n```\n\n#### Output\n```scheme\n((name . John Doe)\n (age . 43)\n (address\n   (street . 10 Downing Street)\n   (city . London))\n (phones . #(+44 1234567 +44 2345678)))\n```\n\n## Installation\n\nbefore installing, make sure you have Guile and make installed.\n### Installing make on Debian / Ubuntu\n```bash\nsudo apt-get install build-essential\n```\n\nOnce you've installed make, run the following command to install gson.\n```bash\ngit clone https://github.com/ayys/gson.git\ncd gson\nsudo make install\n```\n\n## Documentation\n\nGSON module exports size procedures in total. The definition and usage\nexamples of each of the procedures is given below.\n\n### json-string-\u003escm\n\n```scheme\njson-string-\u003escm (string #:optional #:key number-hook nil-hook\n    list-hook object-hook string-hook boolean-hook)\n```\nParse a JSON string into scheme expression. It optionally takes hooks\nfor various JSON data-types. Hooks are described in a [separate section](#hooks).\n\n#### Example\n\n**sample.scm**\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n;;; define code to be a string containing json\n(define code \"[1, 2, 3]\")\n\n;;; Convert JSON string to scheme expressions\n(display (json-string-\u003escm code))\n```\n\n##### Output\n```scheme\n#(1 2 3)\n```\n\n### json-port-\u003escm\n\n```scheme\njson-port-\u003escm (port #:optional #:key number-hook nil-hook\n    list-hook object-hook string-hook boolean-hook)\n```\nA wrapper around [json-string-\u003escm](#json-string-scm) which reads takes a port called\n`port' for JSON string and outputs scheme expression. optional hook\narguments are explained in a [separate section](#hooks).\n\n#### Example\n\n**sample.json**\n```json\n{\"menu\": {\n  \"id\": \"file\",\n  \"value\": \"File\",\n  \"popup\": {\n    \"menuitem\": [\n      {\"value\": \"New\", \"onclick\": \"CreateNewDoc()\"},\n      {\"value\": \"Open\", \"onclick\": \"OpenDoc()\"},\n      {\"value\": \"Close\", \"onclick\": \"CloseDoc()\"}\n    ]\n  }\n}}\n```\n\n**sample.scm**\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n(call-with-input-file (cadr (command-line))\n    (lambda (port) (display (json-string-\u003escm code))))\n```\n\n##### Output\n```scheme\n((\"menu\"\n  (\"id\" . \"file\")\n  (\"value\" . \"File\")\n  (\"popup\"\n   (\"menuitem\" . #(((\"value\" . \"New\") (\"onclick\" . \"CreateNewDoc()\"))\n                   ((\"value\" . \"Open\") (\"onclick\" . \"OpenDoc()\"))\n                   ((\"value\" . \"Close\") (\"onclick\" . \"CloseDoc()\")))))))\n```\n### json-file-\u003escm\n\n```scheme\njson-file-\u003escm (filename #:optional #:key number-hook nil-hook\n    list-hook object-hook string-hook boolean-hook)\n```\nA file-wrapper around  [json-string-\u003escm](#json-string-scm) procedure that takes a filename\nas argument and outputs scheme expressions that correspond to the JSON\ndata in given file. Optional hook arguments are explain in a [separate section](#hooks).\n#### Example\n\n**sample.json**\n```json\n{\"widget\": {\n    \"debug\": \"on\",\n    \"window\": {\n        \"title\": \"Sample Konfabulator Widget\",\n        \"name\": \"main_window\",\n        \"width\": 500,\n        \"height\": 500\n    },\n    \"image\": {\n        \"src\": \"Images/Sun.png\",\n        \"name\": \"sun1\",\n        \"hOffset\": 250,\n        \"vOffset\": 250,\n        \"alignment\": \"center\"\n    },\n    \"text\": {\n        \"data\": \"Click Here\",\n        \"size\": 36,\n        \"style\": \"bold\",\n        \"name\": \"text1\",\n        \"hOffset\": 250,\n        \"vOffset\": 100,\n        \"alignment\": \"center\",\n        \"onMouseUp\": \"sun1.opacity = (sun1.opacity / 100) * 90;\"\n    }\n}}\n```\n\n**sample.scm**\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n;;; Convert JSON string to scheme expressions\n(display (json-file-\u003escm \"sample.json\"))\n```\n\n##### Output\n```scheme\n((\"widget\"\n  (\"debug\" . \"on\")\n  (\"window\"\n   (\"title\" . \"Sample Konfabulator Widget\")\n   (\"name\" . \"main_window\")\n   (\"width\" . 500)\n   (\"height\" . 500))\n  (\"image\"\n   (\"src\" . \"Images/Sun.png\")\n   (\"name\" . \"sun1\")\n   (\"hOffset\". 250)\n   (\"vOffset\" . 250)\n   (\"alignment\" . \"center\"))\n  (\"text\"\n   (\"data\" . \"Click Here\")\n   (\"size\" . 36)\n   (\"style\" . \"bold\")\n   (\"name\" . \"text1\")\n   (\"hOffset\" . 250)\n   (\"vOffset\". 100)\n   (\"alignment\" . \"center\")\n   (\"onMouseUp\" . \"sun1.opacity = (sun1.opacity / 100) * 90;\"))))\n```\n\n\n### scm-\u003ejson-string\n```scheme\nscm-\u003ejson-string (val)\n```\nTakes scheme expression as `val`, and converts it to JSON expression. For\nconversion datatypes, refer to [default conversion format](#default-conversion-format).\n\n#### Example\n\n**sample.scm**\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n;;; define code to be a string containing json\n(define code \"#(1 #f 3)\")\n\n;;; Convert JSON string to scheme expressions\n(display (scm-\u003ejson-string code))\n```\n\n##### Output\n```scheme\n[1, false, 3]\n```\n\n### scm-\u003ejson-port\n\n```scheme\nscm-\u003ejson-port (port code)\n```\nThis is a wrapper around [scm-\u003ejson-string](#scm-json-string) which\ntakes in an input port, reads scm data from it and converts it to JSON\nstring. For more details on conversion, refer to [default conversion format](#default-conversion-format).\n\n### scm-\u003ejson-file\n\n```scheme\nscm-\u003ejson-file (filename code)\n```\nThis is a wrapper around [scm-\u003ejson-string](#scm-json-string) which\ntakes in an input filename, reads scm data from it and converts it to JSON string.\nFor more details on conversion, refer to [default conversion format](#default-conversion-format).\n\n### Hooks\ngson hooks are optional keyword arguments sent to\n[json-string-\u003escm](#json-string-scm),\n[json-port-\u003escm](#json-port-scm), [json-file-\u003escm](#json-file-scm)\nprocedures which are then applied to the scheme expressions parsed from\nthe input JSON. Hooks let the user transform the output of the parser.\n\nBy default, JSON data is converted into scheme expressions based on\nthe [default conversion format](#default-conversion-format). You can\nchange this via hooks.\n\n#### Example of json-string-\u003escm with hooks\n\n```scheme\n;;; Import gson\n(use-modules (gson))\n\n;;; define code to be a string containing json\n(define code \"[4, \\\"two\\\", false]\")\n\n;;; Convert JSON string to scheme expressions\n(display\n    (json-string-\u003escm\n        code\n            #:number-hook (lambda (num-or-string) (1+ num-or-string))\n            #:string-hook (lambda (string) (string-length string))\n            #:boolean-hook (lambda (bool) (not bool))))\n```\n\n##### Output\n```scheme\n#(5 3 #t)\n```\n\n#### object-hook\nobject-hook is an optional procedure that will be called with the\nresult of any JSON objects decoded (a [List](https://www.gnu.org/software/guile/manual/html_node/Lists.html)). The return value of the\nobject-hook will be used instead of the\n[list](https://www.gnu.org/software/guile/manual/html_node/Lists.html).\n\nobject-hook takes in a list as argument and produces any output.\n\n##### Example\n```scheme\n(lambda (lst)\n    (list-\u003evector lst))\n```\n\n#### list-hook\nlist-hook is another optional procedure that will be called on the\nresult of any JSON lists decoded (a\n[Vector](https://www.gnu.org/software/guile/manual/html_node/Vectors.html)). The\nresulting value will be used in place of the vector.\n\nobject-hook takes in a vector as argument and produces any output.\n\n##### Example\n```scheme\n(lambda (vector)\n    (vector-\u003elist lst))\n```\n\n#### number-hook\nnumber-hook is a optional procedure that is called on any\n[numbers](https://www.gnu.org/software/guile/manual/html_node/Numbers.html)\nor\n[strings](https://www.gnu.org/software/guile/manual/html_node/Strings.html)\nencountered while decoding JSON data. The resulting value\nis used in place of the number.\n\nobject-hook takes in a number/string as argument and produces any output.\n\n##### Example\n```scheme\n(lambda (num-or-string)\n    (if (number? num-or-string)\n        (1+ num-or-string)\n        0))\n```\n\n#### string-hook\nstring-hook, as the name suggests is called everything the gson parses\na\n[string](https://www.gnu.org/software/guile/manual/html_node/Strings.html).\nThe resulting value is used in place of the string.\n\nstring-hook takes in a string as argument and produces any output.\n\n##### Example\n```scheme\n(lambda (string)\n    (string-length string))\n```\nThe example above replaces string with the length of said string.\n\n#### boolean-hook\nboolean-hook is an optional procedure that will be called with the\nresult of any JSON objects decoded (a [boolean](https://www.gnu.org/software/guile/manual/html_node/Booleans.html#Booleans)). The return value of the\nboolean-hook will be used instead of the [boolean](https://www.gnu.org/software/guile/manual/html_node/Booleans.html#Booleans).\n\nboolean-hook takes in a boolean as argument and produces any output.\n\n##### Example\n```scheme\n(lambda (bool)\n    (not string))\n```\n\n#### nil-hook\nBy default, nil in JSON data maps to `#nil` in scheme expression. You\ncan change this with the nil-hook that is a procedure which is called\non all the nil values in JSON data. The output of that procedure is\nused instead of #nil.\n\n##### Example\n```scheme\n(lambda (nil-value) #f)\n```\nThis example shows a hook that maps nil value to `#f`.\n\n### Exception Handling\nA GSON-JSON-INVALID exception is thrown if an error is found during\nJSON parsing with a list of two elements as argument. The first\nelement of list contains line number and second element contains\ncolumn number wherein the syntax error occurred.\n\nHere is a simple example to demonstrate exception handling with gson.\n\n```scheme\n(use-modules\n (gson)\n (ice-9 format))\n\n;;; Incorrect JSON - Notice the comma after closing square bracket\n(define code \"[1, 2],\")\n\n(define x (catch GSON-JSON-INVALID\n            (lambda ()\n              (json-string-\u003escm code))\n            (lambda (key . args)\n              (let ((line (caar args))\n                    (column (cadar args)))\n                (format #t \"Error: Syntax error on line ~d:~d\\n\" line column)\n                #f))))\n\n(if x (display x))\n(newline)\n\n```\n\n##### Output\n```\nError: Syntax error on line 0:6\n```\nNotice in the above example, the input JSON string contained syntax\nerror after the closing square-bracket. The error was thrown by gson\nand caught by the user after which a clean error message was printed\nto the default output.\n\n### Default Conversion Format\n| JSON Datatype | Guile Datatype    |\n|---------------|-------------------|\n| String        | String            |\n| Number        | *Number or String |\n| false         | #f                |\n| true          | #t                |\n| nil           | #nil              |\n| List          | Vector            |\n| Object        | **List of pairs   |\n\n\\* If a number is too large to be represented in Guile, it is\nrepresented as a string.\n\n\\*\\* The first element of pair is the key, second element is the value\nfor each property of JSON object.\n\n## License\nCopyright (C) 2020 Ayush Jha \u003cayushjha@pm.me\u003e\n\ngson is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 3 of the License, or (at your\noption) any later version.\n\ngson is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\nGeneral Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with gson. If not, see https://www.gnu.org/licenses/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayys%2Fgson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayys%2Fgson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayys%2Fgson/lists"}