[skip ci] Changing the API for retrieving lexemes: there is now a 'sp…

…an' structure that holds the code unit index and length.
railgunlabs · Feb 18, 2025 · d715fef · d715fef
1 parent 3d3c33f
commit d715fef
Show file tree

Hide file tree

Showing 36 changed files with 143 additions and 149 deletions.
diff --git a/configure.ac b/configure.ac
@@ -1,6 +1,6 @@
 # Specify the project and version + the minimum automake version required.
 AC_PREREQ(2.66)
-AC_INIT([judo], [1.0.0-rc1])
+AC_INIT([judo], [1.0.0-rc2])
 
 # Instruct automake to place all intermediary files into a seperate directory.
 # If this isn't specified, then it will pollute the main directory.

diff --git a/examples/parser.c b/examples/parser.c
@@ -43,7 +43,7 @@ void *memfunc(void *user_data, void *ptr, size_t size)
 
 void print_tree(const char *source, struct judo_value *value)
 {
-    int32_t index, length;
+    struct judo_span span;
     struct judo_value *elem;
     struct judo_member *member;
 
@@ -54,8 +54,8 @@ void print_tree(const char *source, struct judo_value *value)
     case JUDO_TYPE_BOOL:
     case JUDO_TYPE_NUMBER:
     case JUDO_TYPE_STRING:
-        judo_value2span(value, &index, &length);
-        printf("%.*s", length, &source[index]);
+        span = judo_value2span(value);
+        printf("%.*s", span.length, &source[span.offset]);
         break;
     // [cont...]
 //! [parser_process_traverse]
@@ -84,8 +84,8 @@ void print_tree(const char *source, struct judo_value *value)
         member = judo_membfirst(value);
         while (member != NULL)
         {
-            judo_name2span(member, &index, &length);
-            printf("%.*s:", length, &source[index]);
+            span = judo_name2span(member);
+            printf("%.*s:", span.length, &source[span.offset]);
             print_tree(source, judo_membvalue(member));
             if (judo_membnext(member) != NULL)
             {

diff --git a/examples/scanner.c b/examples/scanner.c
@@ -37,13 +37,13 @@ static void process_element(struct judo_stream stream, const char *json)
     case JUDO_OBJECT_PUSH: puts("{push}"); break;
     case JUDO_OBJECT_POP: puts("{pop}"); break;
     case JUDO_NUMBER:
-        printf("number: %.*s\n", stream.length, &json[stream.where]);
+        printf("number: %.*s\n", stream.where.length, &json[stream.where.offset]);
         break;
     case JUDO_STRING:
-        printf("string: %.*s\n", stream.length, &json[stream.where]);
+        printf("string: %.*s\n", stream.where.length, &json[stream.where.offset]);
         break;
     case JUDO_OBJECT_NAME:
-        printf("{name: %.*s}\n", stream.length, &json[stream.where]);
+        printf("{name: %.*s}\n", stream.where.length, &json[stream.where.offset]);
         break;
     default:
         break;

diff --git a/include/judo.h b/include/judo.h
@@ -62,14 +62,20 @@ enum judo_element
     JUDO_EOF
 };
 
+// A range of UTF-8 code units in the JSON source text.
+struct judo_span
+{
+    int32_t offset;
+    int32_t length;
+};
+
 // Field names beginning with "s_" are private to the scanner implementation and must not be accessed.
 struct judo_stream
 {
 #ifndef DOXYGEN
     int32_t s_at;
 #endif
-    int32_t where;
-    int32_t length;
+    struct judo_span where;
     enum judo_element element;
 #ifndef DOXYGEN
     int8_t s_stack;
@@ -96,8 +102,7 @@ enum judo_type
 
 struct judo_error
 {
-    int32_t where;
-    int32_t length;
+    struct judo_span where;
     char description[JUDO_ERRMAX];
 };
 #endif
@@ -133,8 +138,8 @@ judo_member *judo_membfirst(judo_value *value);
 judo_member *judo_membnext(judo_member *member);
 judo_value *judo_membvalue(judo_member *member);
 
-enum judo_result judo_name2span(const judo_member *member, int32_t *lexeme, int32_t *length);
-enum judo_result judo_value2span(const judo_value *value, int32_t *lexeme, int32_t *length);
+struct judo_span judo_name2span(const judo_member *member);
+struct judo_span judo_value2span(const judo_value *value);
 #endif
 
 #endif
diff --git a/man/judo.3 b/man/judo.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo.h \- embeddable JSON Parser
 .SH LIBRARY
@@ -55,12 +55,12 @@ for (;;) {
 .in
 .PP
 After each call to \f[B]judo_scan\f[R](3), you can inspect certain fields of the \f[B]judo_stream\f[R](3) structure.
-These fields are \f[I]element\f[R], \f[I]where\f[R], \f[I]length\f[R], and \f[I]error\f[R].
+These fields are \f[I]element\f[R], \f[I]where\f[R], and \f[I]error\f[R].
 .PP
 The value of the \f[I]element\f[R] field is one of the \f[B]judo_element\f[R](3) enumeration constants.
 It describes the semantic element that was just processed.
 .PP
-The \f[I]where\f[R] and \f[I]length\f[R] fields describe the span of UTF-8 code units where the semantic element was found in the source text.
+The \f[I]where\f[R] field describe the span of UTF-8 code units where the semantic element was found in the source text.
 In the case of literal values, like numbers and strings, the span of code units defines its lexeme.
 .PP
 The \f[I]error\f[R] field is a null-terminated UTF-8 encoded string that describes the details of any error in US English.
@@ -80,7 +80,7 @@ This function accepts a \f[B]judo_number\f[R](3) which is a floating point stora
 .in +4n
 .EX
 judo_number number;
-judo_numberify(&source[stream.where], stream.length, &number);
+judo_numberify(&source[stream.where.offset], stream.where.length, &number);
 .EE
 .in
 .PP
@@ -95,7 +95,7 @@ The implementation will update this parameter with the number of code units writ
 .EX
 char buf[32];
 int32_t buflen = sizeof(buf);
-judo_stringify(&source[stream.where], stream.length, buf, &buflen);
+judo_stringify(&source[stream.where.offset], stream.where.length, buf, &buflen);
 .EE
 .in
 .PP
@@ -110,7 +110,7 @@ You can then call the function again with a buffer of the appropriate size.
 .in +4n
 .EX
 buflen = 0;
-judo_stringify(&source[stream.where], stream.length, NULL, &buflen);
+judo_stringify(&source[stream.where.offset], stream.where.length, NULL, &buflen);
 .EE
 .in
 .PP
@@ -120,7 +120,7 @@ If an error occurs, then the \f[B]judo_scan\f[R](3) function will return a \f[B]
 The result code indicates the general classification of the error, e.g. syntax error, bad encoding, etc.
 Regardless of the error code, the \f[I]error\f[R] field of the \f[B]judo_stream\f[R](3) structure will be populated with a UTF-8 encoded error message written in US English.
 .PP
-Additionally, the \f[I]where\f[R] and \f[I]length\f[R] fields will be populated with the code unit index and count which together communicate the span of code units where the error was detected in the JSON source text.
+Additionally, the \f[I]where\f[R] field will be populated with the code unit index and count which together communicate the span of code units where the error was detected in the JSON source text.
 The span can be used to derive line and column numbers for more detailed error reporting.
 .SS Saving state
 .PP
@@ -234,10 +234,8 @@ Once you have the lexeme, you can use \f[B]judo_numberify\f[R](3) to convert it
 .in +4n
 .EX
 if (judo_gettype(root) == JUDO_TYPE_NUMBER) {
-    int32_t index, length;
-    if (judo_value2span(root, &index, &length) == JUDO_SUCCESS) {
-        // Use the lexeme span to extract the float value.
-    }
+    struct judo_span lexeme = judo_value2span(root);
+    // Use the lexeme span to extract the float value.
 }
 .EE
 .in
@@ -251,10 +249,8 @@ Once you have the lexeme, you can use \f[B]judo_stringify\f[R](3) to decode it.
 .in +4n
 .EX
 if (judo_gettype(root) == JUDO_TYPE_STRING) {
-    int32_t index, length;
-    if (judo_value2span(root, &index, &length) == JUDO_SUCCESS) {
-        // Use the lexeme span to decode the string.
-    }
+    struct judo_span lexeme = judo_value2span(root);
+    // Use the lexeme span to extract the float value.
 }
 .EE
 .in

diff --git a/man/judo_element.3 b/man/judo_element.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_element \- semantic element
 .SH LIBRARY

diff --git a/man/judo_errmax.3 b/man/judo_errmax.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 JUDO_ERRMAX \- maximum error description length
 .SH LIBRARY

diff --git a/man/judo_error.3 b/man/judo_error.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_error
 .SH LIBRARY
@@ -9,8 +9,7 @@ Embeddable JSON parser (libjudo, -ljudo)
 .PP
 .B struct judo_error {
 .RS
-.B int32_t where;
-.B int32_t length;
+.B struct judo_span where;
 .B char description[JUDO_ERRMAX];
 .RE
 .B };
@@ -19,7 +18,7 @@ Embeddable JSON parser (libjudo, -ljudo)
 This structure will be populated with error information if \f[B]judo_parse\f[R](3) fails.
 .PP
 The \f[I]description\f[R] field will be populated with a UTF-8 encoded error message written in US English.
-The \f[I]where\f[R] and \f[I]length\f[R] fields will be populated with the span of code units where the error was detected in the JSON source text.
+The \f[I]where\f[R] field will be populated with the span of code units where the error was detected in the JSON source text.
 You can use the span of code units to derive line and column numbers for more detailed error reporting.
 .SH SEE ALSO
 .BR judo_parse (3)

diff --git a/man/judo_first.3 b/man/judo_first.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_first \- first array element
 .SH LIBRARY

diff --git a/man/judo_free.3 b/man/judo_free.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_free \- free the in-memory tree
 .SH LIBRARY

diff --git a/man/judo_gettype.3 b/man/judo_gettype.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_gettype \- type of a JSON value
 .SH LIBRARY

diff --git a/man/judo_len.3 b/man/judo_len.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_len \- array or object length
 .SH LIBRARY

diff --git a/man/judo_maxdepth.3 b/man/judo_maxdepth.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 JUDO_MAXDEPTH \- maximum nesting depth
 .SH LIBRARY

diff --git a/man/judo_member.3 b/man/judo_member.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_member \- object member
 .SH LIBRARY

diff --git a/man/judo_membfirst.3 b/man/judo_membfirst.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_membfirst \- first object member
 .SH LIBRARY

diff --git a/man/judo_membnext.3 b/man/judo_membnext.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_membnext \- next object member
 .SH LIBRARY

diff --git a/man/judo_membvalue.3 b/man/judo_membvalue.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_membvalue \- member value
 .SH LIBRARY

diff --git a/man/judo_memfunc.3 b/man/judo_memfunc.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_memfunc \- memory manager
 .SH LIBRARY

diff --git a/man/judo_name2span.3 b/man/judo_name2span.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_name2span \- member name lexeme
 .SH LIBRARY
@@ -7,18 +7,13 @@ Embeddable JSON parser (libjudo, -ljudo)
 .nf
 .B #include <judo.h>
 .PP
-.BI "enum judo_result judo_name2span(const judo_member *" member ", int32_t *" lexeme ", int32_t *" length ");"
+.BI "struct judo_span judo_name2span(const judo_member *" member ");"
 .fi
 .SH DESCRIPTION
-The \f[B]judo_name2span\f[R](3) function populates \f[I]lexeme\f[R] and \f[I]length\f[R] with the span of code units of the lexeme of \f[I]member\f[R] name in the JSON source text.
+The \f[B]judo_name2span\f[R](3) function returns the lexeme of \f[I]member\f[R] name in the JSON source text as a span of UTF-8 code units.
 The name is referred to as a “key” in JavaScript terminology.
 .SH RETURN VALUE
-.TP
-JUDO_SUCCESS
-If the lexeme was extracted successfully.
-.TP
-JUDO_INVALID_OPERATION
-If \f[C]value\f[R], \f[I]lexeme\f[R], or \f[I]length\f[R] are NULL.
+Code unit range of the lexeme.
 .SH SEE ALSO
 .BR judo_member (3)
 .SH AUTHOR

diff --git a/man/judo_next.3 b/man/judo_next.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_next \- next array element
 .SH LIBRARY

diff --git a/man/judo_number.3 b/man/judo_number.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_number \- floating-point storage type
 .SH LIBRARY

diff --git a/man/judo_numberify.3 b/man/judo_numberify.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_numberify \- lexeme to float
 .SH LIBRARY

diff --git a/man/judo_parse.3 b/man/judo_parse.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_parse \- build an in-memory tree
 .SH LIBRARY

diff --git a/man/judo_result.3 b/man/judo_result.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_result \- function status code
 .SH LIBRARY

diff --git a/man/judo_scan.3 b/man/judo_scan.3
@@ -1,4 +1,4 @@
-.TH "JUDO" "3" "Feb 14th 2025" "Judo 1.0.0-rc1"
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
 .SH NAME
 judo_scan \- incrementally scan JSON
 .SH LIBRARY

diff --git a/man/judo_span.3 b/man/judo_span.3
@@ -0,0 +1,33 @@
+.TH "JUDO" "3" "Feb 18th 2025" "Judo 1.0.0-rc2"
+.SH NAME
+judo_span
+.SH LIBRARY
+Embeddable JSON parser (libjudo, -ljudo)
+.SH SYNOPSIS
+.nf
+.B #include <judo.h>
+.PP
+.B struct judo_span {
+.RS
+.B int32_t offset;
+.B int32_t length;
+.RE
+.B };
+.fi
+.SH DESCRIPTION
+The structure describes a range of UTF-8 code units.
+.SH AUTHOR
+.UR https://railgunlabs.com
+Railgun Labs
+.UE .
+.SH INTERNET RESOURCES
+The online documentation is
+.UR https://railgunlabs.com/judo
+published here
+.UE .
+.SH LICENSING
+Judo is Free Software distributed under the GNU General Public License version 3 as published by the Free Software Foundation.
+Alternatively, you can license the library under a proprietary license, as set out on the
+.UR https://railgunlabs.com/judo/license/
+Railgun Labs website
+.UE .