Restructuring and improving documentation.

README.md

@@ -518,6 +518,17 @@ The modules that ship with Scryer Prolog are also called
 * [`csv`](src/lib/csv.pl)
   `parse_csv//1` and `parse_csv//2` can be used with [`phrase_from_file/2`](src/lib/pio.pl)
   or [`phrase/2`](src/lib/dcgs.pl) to parse csv
+* [`serialization/abnf`](src/lib/serialization/abnf.pl)
+  DCGs describing the
+  [ABNF grammar core (RFC 5234)](https://tools.ietf.org/html/rfc5234#appendix-B.1),
+  which is used to describe many [IETF](https://www.ietf.org/standards/rfcs/)
+  syntaxes, such as [HTTP v1.1](https://www.rfc-editor.org/rfc/rfc7230.html#page-82),
+  [SMTP](https://www.rfc-editor.org/rfc/rfc5321.html),
+  [iCalendar](https://www.rfc-editor.org/rfc/rfc5545.html), and more.
+* [`serialization/json`](src/lib/serialization/json.pl)
+  `json_chars//1` can be used with [`phrase_from_file/2`](src/lib/pio.pl)
+  or [`phrase/2`](src/lib/dcgs.pl) to parse and generate
+  [JSON](https://www.json.org/json-en.html).
 * [`xpath`](src/lib/xpath.pl)
   The predicate `xpath/3` is used for convenient reasoning about HTML
   and XML documents, inspired by the XPath language. This library
@@ -539,8 +550,6 @@ The modules that ship with Scryer Prolog are also called
   ECDH key exchange over Curve25519 (X25519), authenticated symmetric
   encryption with ChaCha20-Poly1305, and reasoning about elliptic curves.
 * [`uuid`](src/lib/uuid.pl) UUIDv4 generation and hex representation
-* [`json`](src/lib/json.pl) [JSON](https://www.json.org/json-en.html)
-  parsing and generation (beta version, subject to interface changes).
 
 To use predicates provided by the `lists` library, write:
 

src/lib/charsio.pl

@@ -4,23 +4,7 @@
                     read_line_to_chars/3,
                     read_term_from_chars/2,
                     write_term_to_chars/3,
-                    chars_base64/3,
+                    chars_base64/3]).
-                    abnf_alpha//1,
-                    abnf_bit//1,
-                    abnf_char//1,
-                    abnf_cr//0,
-                    abnf_crlf//0,
-                    abnf_ctl//1,
-                    abnf_digit//1,
-                    abnf_dquote//0,
-                    abnf_hexdig//1,
-                    abnf_htab//0,
-                    abnf_lf//0,
-                    abnf_lwsp//0,
-                    abnf_octet//1,
-                    abnf_sp//0,
-                    abnf_vchar//1,
-                    abnf_wsp//0 ]).
 
 :- use_module(library(dcgs)).
 :- use_module(library(iso_ext)).
@@ -258,112 +242,3 @@ chars_base64(Cs, Bs, Options) :-
             maplist(must_be(character), Cs),
             '$chars_base64'(Cs, Bs, Padding, Charset)
         ).
-
-/*  [Core Rules](https://tools.ietf.org/html/rfc5234#appendix-B.1) of the
-    Augmented Backus-Naur Form specification (ABNF - RFC 5234). ABNF commonly
-    serves as the definition language for IETF communication protocols, so
-    having these DCGs can be extremely useful for reasoning about most IETF
-    syntaxes. The DCGs are presented in the order they appear in the RFC.
-    While some DCGs below use `char_type/2`, the most common ones are defined
-    manually in order to take advantage of Prolog's first-argument indexing. */
-abnf_alpha('a') --> "a".
-abnf_alpha('b') --> "b".
-abnf_alpha('c') --> "c".
-abnf_alpha('d') --> "d".
-abnf_alpha('e') --> "e".
-abnf_alpha('f') --> "f".
-abnf_alpha('g') --> "g".
-abnf_alpha('h') --> "h".
-abnf_alpha('i') --> "i".
-abnf_alpha('j') --> "j".
-abnf_alpha('k') --> "k".
-abnf_alpha('l') --> "l".
-abnf_alpha('m') --> "m".
-abnf_alpha('n') --> "n".
-abnf_alpha('o') --> "o".
-abnf_alpha('p') --> "p".
-abnf_alpha('q') --> "q".
-abnf_alpha('r') --> "r".
-abnf_alpha('s') --> "s".
-abnf_alpha('t') --> "t".
-abnf_alpha('u') --> "u".
-abnf_alpha('v') --> "v".
-abnf_alpha('w') --> "w".
-abnf_alpha('x') --> "x".
-abnf_alpha('y') --> "y".
-abnf_alpha('z') --> "z".
-abnf_alpha('A') --> "A".
-abnf_alpha('B') --> "B".
-abnf_alpha('C') --> "C".
-abnf_alpha('D') --> "D".
-abnf_alpha('E') --> "E".
-abnf_alpha('F') --> "F".
-abnf_alpha('G') --> "G".
-abnf_alpha('H') --> "H".
-abnf_alpha('I') --> "I".
-abnf_alpha('J') --> "J".
-abnf_alpha('K') --> "K".
-abnf_alpha('L') --> "L".
-abnf_alpha('M') --> "M".
-abnf_alpha('N') --> "N".
-abnf_alpha('O') --> "O".
-abnf_alpha('P') --> "P".
-abnf_alpha('Q') --> "Q".
-abnf_alpha('R') --> "R".
-abnf_alpha('S') --> "S".
-abnf_alpha('T') --> "T".
-abnf_alpha('U') --> "U".
-abnf_alpha('V') --> "V".
-abnf_alpha('W') --> "W".
-abnf_alpha('X') --> "X".
-abnf_alpha('Y') --> "Y".
-abnf_alpha('Z') --> "Z".
-
-abnf_bit(0) --> "0".
-abnf_bit(1) --> "1".
-
-abnf_char(C) --> [C], { dif(C, '\x0000\'), char_type(C, ascii) }. %'
-
-abnf_cr --> "\r".
-
-abnf_crlf --> "\r\n".
-
-abnf_ctl(C) --> [C], { char_type(C, ascii), char_type(C, control) }.
-
-abnf_digit(0) --> "0".
-abnf_digit(1) --> "1".
-abnf_digit(2) --> "2".
-abnf_digit(3) --> "3".
-abnf_digit(4) --> "4".
-abnf_digit(5) --> "5".
-abnf_digit(6) --> "6".
-abnf_digit(7) --> "7".
-abnf_digit(8) --> "8".
-abnf_digit(9) --> "9".
-
-abnf_dquote --> "\"".
-
-abnf_hexdig(Digit) --> abnf_digit(Digit).
-abnf_hexdig(10) --> "A".
-abnf_hexdig(11) --> "B".
-abnf_hexdig(12) --> "C".
-abnf_hexdig(13) --> "D".
-abnf_hexdig(14) --> "E".
-abnf_hexdig(15) --> "F".
-
-abnf_htab --> "\t".
-
-abnf_lf --> "\n".
-
-abnf_lwsp --> "".
-abnf_lwsp --> abnf_wsp, abnf_lwsp.
-abnf_lwsp --> abnf_clrf, abnf_wsp, abnf_lwsp.
-
-abnf_octet(C) --> [C], char_type(C, octet).
-
-abnf_sp --> " ".
-
-abnf_vchar(C) --> [C], char_type(C, ascii_graphic).
-
-abnf_wsp --> abnf_sp.
-abnf_wsp --> abnf_htab.

src/lib/serialization/abnf.pl

@@ -0,0 +1,166 @@
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   Written Apr 2021 by Aram Panasenco (panasenco@ucla.edu)
+   Part of Scryer Prolog.
+
+   [Core Rules](https://tools.ietf.org/html/rfc5234#appendix-B.1) of the
+   Augmented Backus-Naur Form specification (ABNF - RFC 5234). ABNF commonly
+   serves as the definition language for IETF communication protocols, so
+   having these DCGs can be extremely useful for reasoning about most IETF
+   syntaxes. The DCGs are presented in the order they appear in the RFC.
+   While some DCGs below use `char_type/2`, the most common ones are defined
+   manually in order to take advantage of Prolog's first-argument indexing.
+   
+   BSD 3-Clause License
+   
+   Copyright (c) 2021, Aram Panasenco
+   All rights reserved.
+   
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are met:
+   
+   * Redistributions of source code must retain the above copyright notice, this
+     list of conditions and the following disclaimer.
+   
+   * Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+   
+   * Neither the name of the copyright holder nor the names of its
+     contributors may be used to endorse or promote products derived from
+     this software without specific prior written permission.
+   
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+   CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
+:- module(abnf, [abnf_alpha//1,
+                 abnf_bit//1,
+                 abnf_char//1,
+                 abnf_cr//0,
+                 abnf_crlf//0,
+                 abnf_ctl//1,
+                 abnf_digit//1,
+                 abnf_dquote//0,
+                 abnf_hexdig//1,
+                 abnf_htab//0,
+                 abnf_lf//0,
+                 abnf_lwsp//0,
+                 abnf_octet//1,
+                 abnf_sp//0,
+                 abnf_vchar//1,
+                 abnf_wsp//0 ]).
+
+:- use_module(library(charsio)).
+:- use_module(library(dcgs)).
+:- use_module(library(dif)).
+:- use_module(library(lists)).
+
+abnf_alpha('a') --> "a".
+abnf_alpha('b') --> "b".
+abnf_alpha('c') --> "c".
+abnf_alpha('d') --> "d".
+abnf_alpha('e') --> "e".
+abnf_alpha('f') --> "f".
+abnf_alpha('g') --> "g".
+abnf_alpha('h') --> "h".
+abnf_alpha('i') --> "i".
+abnf_alpha('j') --> "j".
+abnf_alpha('k') --> "k".
+abnf_alpha('l') --> "l".
+abnf_alpha('m') --> "m".
+abnf_alpha('n') --> "n".
+abnf_alpha('o') --> "o".
+abnf_alpha('p') --> "p".
+abnf_alpha('q') --> "q".
+abnf_alpha('r') --> "r".
+abnf_alpha('s') --> "s".
+abnf_alpha('t') --> "t".
+abnf_alpha('u') --> "u".
+abnf_alpha('v') --> "v".
+abnf_alpha('w') --> "w".
+abnf_alpha('x') --> "x".
+abnf_alpha('y') --> "y".
+abnf_alpha('z') --> "z".
+abnf_alpha('A') --> "A".
+abnf_alpha('B') --> "B".
+abnf_alpha('C') --> "C".
+abnf_alpha('D') --> "D".
+abnf_alpha('E') --> "E".
+abnf_alpha('F') --> "F".
+abnf_alpha('G') --> "G".
+abnf_alpha('H') --> "H".
+abnf_alpha('I') --> "I".
+abnf_alpha('J') --> "J".
+abnf_alpha('K') --> "K".
+abnf_alpha('L') --> "L".
+abnf_alpha('M') --> "M".
+abnf_alpha('N') --> "N".
+abnf_alpha('O') --> "O".
+abnf_alpha('P') --> "P".
+abnf_alpha('Q') --> "Q".
+abnf_alpha('R') --> "R".
+abnf_alpha('S') --> "S".
+abnf_alpha('T') --> "T".
+abnf_alpha('U') --> "U".
+abnf_alpha('V') --> "V".
+abnf_alpha('W') --> "W".
+abnf_alpha('X') --> "X".
+abnf_alpha('Y') --> "Y".
+abnf_alpha('Z') --> "Z".
+
+abnf_bit(0) --> "0".
+abnf_bit(1) --> "1".
+
+abnf_char(C) --> [C], { dif(C, '\x0000\'), char_type(C, ascii) }. %'
+
+abnf_cr --> "\r".
+
+abnf_crlf --> "\r\n".
+
+abnf_ctl(C) --> [C], { char_type(C, ascii), char_type(C, control) }.
+
+abnf_digit(0) --> "0".
+abnf_digit(1) --> "1".
+abnf_digit(2) --> "2".
+abnf_digit(3) --> "3".
+abnf_digit(4) --> "4".
+abnf_digit(5) --> "5".
+abnf_digit(6) --> "6".
+abnf_digit(7) --> "7".
+abnf_digit(8) --> "8".
+abnf_digit(9) --> "9".
+
+abnf_dquote --> "\"".
+
+abnf_hexdig(Digit) --> abnf_digit(Digit).
+abnf_hexdig(10) --> "A".
+abnf_hexdig(11) --> "B".
+abnf_hexdig(12) --> "C".
+abnf_hexdig(13) --> "D".
+abnf_hexdig(14) --> "E".
+abnf_hexdig(15) --> "F".
+
+abnf_htab --> "\t".
+
+abnf_lf --> "\n".
+
+abnf_lwsp --> "".
+abnf_lwsp --> abnf_wsp, abnf_lwsp.
+abnf_lwsp --> abnf_clrf, abnf_wsp, abnf_lwsp.
+
+abnf_octet(C) --> [C], char_type(C, octet).
+
+abnf_sp --> " ".
+
+abnf_vchar(C) --> [C], char_type(C, ascii_graphic).
+
+abnf_wsp --> abnf_sp.
+abnf_wsp --> abnf_htab.

src/lib/serialization/json.pl

@@ -2,6 +2,9 @@
    Written Apr 2021 by Aram Panasenco (panasenco@ucla.edu)
    Part of Scryer Prolog.
 
+   `json_chars//1` can be used with [`phrase_from_file/2`](src/lib/pio.pl)
+   or [`phrase/2`](src/lib/dcgs.pl) to parse and generate [JSON](https://www.json.org/json-en.html).
+   
    BSD 3-Clause License
    
    Copyright (c) 2021, Aram Panasenco
@@ -37,10 +40,10 @@
                  json_chars//1
                 ]).
 
-:- use_module(library(charsio)).
 :- use_module(library(dcgs)).
 :- use_module(library(dif)).
 :- use_module(library(lists)).
+:- use_module(library(serialization/abnf)).
 
 /*  The DCGs are written to match the McKeeman form presented on the right side of https://www.json.org/json-en.html 
     as closely as possible. Note that the names in the McKeeman form conflict with the pictures on the site. */

src/tests/json/test_json.pl

@@ -3,11 +3,11 @@
 :- use_module(library(charsio)).
 :- use_module(library(dcgs)).
 :- use_module(library(format)).
-:- use_module(library(json)).
+:- use_module(library(iso_ext)).
 :- use_module(library(lists)).
 :- use_module(library(os)).
 :- use_module(library(pio)).
-:- use_module(library(iso_ext)).
+:- use_module(library(serialization/json)).
 :- use_module(library(time)).
 
 test_path(TestName, TestPath) :-