From ddf1ceaccb9d62f8b1bce1b75b316fba646b8f8a Mon Sep 17 00:00:00 2001 From: ccamel Date: Tue, 8 Oct 2024 18:23:29 +0200 Subject: [PATCH] docs(logic): describe JSON canonical representation --- docs/predicate/json_prolog_2.md | 17 +++++++++++++---- x/logic/predicate/json.go | 15 +++++++++++++-- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/predicate/json_prolog_2.md b/docs/predicate/json_prolog_2.md index bd803abf7..49ca6d658 100644 --- a/docs/predicate/json_prolog_2.md +++ b/docs/predicate/json_prolog_2.md @@ -7,7 +7,7 @@ sidebar_position: 15 ## Description -`json_prolog/2` is a predicate that will unify a JSON string into prolog terms and vice versa. +`json_prolog/2` is a predicate that unifies a JSON into a prolog term and vice versa. The signature is as follows: @@ -17,10 +17,19 @@ json_prolog(?Json, ?Term) is det Where: -- Json is the string representation of the json -- Term is an Atom that would be unified by the JSON representation as Prolog terms. +- Json is the textual representation of the JSON, as either an atom, a list of character codes, or a list of characters. +- Term is the Prolog term that represents the JSON structure. -In addition, when passing Json and Term, this predicate return true if both result match. +## JSON canonical representation + +The canonical representation for Term is: + +- A JSON object is mapped to a Prolog term json\(NameValueList\), where NameValueList is a list of Name\-Value pairs. Name is an atom created from the JSON string. +- A JSON array is mapped to a Prolog list of JSON values. +- A JSON string is mapped to a Prolog atom. +- A JSON number is mapped to a Prolog number. +- The JSON constants true and false are mapped to @\(true\) and @\(false\). +- The JSON constant null is mapped to the Prolog term @\(null\). ## Examples diff --git a/x/logic/predicate/json.go b/x/logic/predicate/json.go index 1f94f9507..8fdbf7271 100644 --- a/x/logic/predicate/json.go +++ b/x/logic/predicate/json.go @@ -23,8 +23,19 @@ import ( // json_prolog(?Json, ?Term) is det // // Where: -// - Json is the textual representation of the json, as an atom, a list of character codes, or list of characters. -// - Term is a term that represents the JSON in the prolog world. +// - Json is the textual representation of the JSON, as either an atom, a list of character codes, or a list of characters. +// - Term is the Prolog term that represents the JSON structure. +// +// # JSON canonical representation +// +// The canonical representation for Term is: +// - A JSON object is mapped to a Prolog term json(NameValueList), where NameValueList is a list of Name-Value pairs. +// Name is an atom created from the JSON string. +// - A JSON array is mapped to a Prolog list of JSON values. +// - A JSON string is mapped to a Prolog atom. +// - A JSON number is mapped to a Prolog number. +// - The JSON constants true and false are mapped to @(true) and @(false). +// - The JSON constant null is mapped to the Prolog term @(null). // // # Examples: //