[PATCH 1/2] pk_parse_version: Provide more context on parse failure

[Arsen Arsenović]

* libpoke/std.pk (raise_exception): New function, takes an
exception and augments it with more context, to create a new
exception.  Intended as a helper for errors during parsing.
(pk_parse_version): Use new raise_exception facility.
* doc/poke.texi (strtok): Document raise_exception.
---
Evening,

This patchset implements the discussed changes to pk_parse_version, to permit
parsing and comparing strings automatically, and the more contextually rich
errors.

OK for master?

Thanks in advance.

 ChangeLog      |  8 ++++++++
 doc/poke.texi  | 12 +++++++++++-
 libpoke/std.pk | 25 ++++++++++++++++++-------
 3 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 354135da..c9fe04dc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2023-01-31  Arsen Arsenović  <arsen@aarsen.me>
+
+       * libpoke/std.pk (raise_exception): New function, takes an
+       exception and augments it with more context, to create a new
+       exception.  Intended as a helper for errors during parsing.
+       (pk_parse_version): Use new raise_exception facility.
+       * doc/poke.texi (strtok): Document raise_exception.
+
 2023-01-30  Arsen Arsenović  <arsen@aarsen.me>
 
        poke.texi: Remedy syntax-check fails
diff --git a/doc/poke.texi b/doc/poke.texi
index 426c6a8a..98170eb9 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -15804,6 +15804,8 @@ @node strtok
 
     method popdelim = (string @var{delimiters}) string: @{ @dots{} @}
     method poprdelim = (string @var{delimiters}) string: @{ @dots{} @}
+
+    method raise_exception = (Exception @var{base}, string @var{message}) 
void: @{ @dots{} @}
   @}
 
 fun strtok = (string @var{a}) String_Tokenizer: @{ @dots{} @}
@@ -15870,6 +15872,13 @@ @node strtok
 Raises @code{E_out_of_bounds} if at the end of the string.
 @end deftypemethod
 
+@deftypemethod String_Tokenizer void raise_exception @
+               (Exception @var{base}, string @var{message})
+Raises a copy of @var{base} augmented so that it contains a
+description of the tokenizers current position, as well as the
+programmer-specified @var{message}.
+@end deftypemethod
+
 @node Character Functions
 @section Character Functions
 The Poke standard library provides the following functions to deal
@@ -16501,8 +16510,9 @@ @node PVM Instruction Index
 @c  LocalWords:  variadic args PDP programmatically PKL eBPF dst src
 @c  LocalWords:  BPF Insn Regs le ident ei ELFDATA LSB ELFDAT MSB ios
 @c  LocalWords:  Ehdr ELFDATANONE osabi abiversion nident Unmapping
-@c  LocalWords:  Comparator cmp relocations DIEs nelems
+@c  LocalWords:  Comparator cmp relocations DIEs nelems tokenizers
 @c  LocalWords:  EOF Rela Addr Xword Sxword Shdr addr addralign fmt
 @c  LocalWords:  entsize relocs adoleces libtextstyle classname css
 @c  LocalWords:  ushort ulong uoff abc ltrim whitespace rtrim fdl
 @c  LocalWords:  quicksort array'length comparator printindex
+@c  LocalWords:  tokenizer
diff --git a/libpoke/std.pk b/libpoke/std.pk
index 956dede5..cb14351f 100644
--- a/libpoke/std.pk
+++ b/libpoke/std.pk
@@ -556,6 +556,17 @@ type String_Tokenizer =
     string str;
     computed uint<32> more;
 
+    method raise_exception = (Exception base, string message) void:
+    {
+      raise Exception {
+        code = base.code,
+        name = base.name,
+        exit_status = base.exit_status,
+        location = "at position " + ltos (i),
+        msg = message
+      };
+    }
+
     method get_more = uint<32>:
     {
       return i < str'length;
@@ -583,7 +594,7 @@ type String_Tokenizer =
 
       var res = strtoi (str, base, i);
       if (res.off == i)
-        raise E_inval;
+        raise_exception (E_inval, "expected number");
 
       i = res.off;
       return res.val;
@@ -707,7 +718,7 @@ fun pk_version_parse = (string a) Pk_Version:
   var i = strtok (a);
 
   if (!i.more)
-    raise E_inval;
+    i.raise_exception (E_inval, "expected major.minor");
 
   /* Helper that pops an equal character from the tokenizer, and checks that
      it's the desired character.  */
@@ -716,12 +727,12 @@ fun pk_version_parse = (string a) Pk_Version:
     try
       {
         if (i.peek () != x)
-          raise E_inval;
+          i.raise_exception (E_inval, "expected '" + x as string + "'");
         i.i++;
       }
     catch if E_out_of_bounds
       {
-        raise E_inval;
+        i.raise_exception (E_inval, "expected '" + x as string + "', got EOF");
       }
   };
 
@@ -738,7 +749,7 @@ fun pk_version_parse = (string a) Pk_Version:
   catch if E_out_of_bounds
     {
       /* If any of these two are missing, it's an invalid.  */
-      raise E_inval;
+      i.raise_exception (E_inval, "missing mandatory component");
     };
 
   if (!i.more)
@@ -763,13 +774,13 @@ fun pk_version_parse = (string a) Pk_Version:
   catch if E_out_of_bounds
     {
       /* If any of these two are missing, it's an invalid.  */
-      raise E_inval;
+      i.raise_exception (E_inval, "branch-offset component incomplete");
     };
 
   /* We shouldn't have trailing data at this point, beyond the -gXDIGIT string,
      or the -dirty string, but both should be stripped already.  */
   if (i.more)
-    raise E_inval;
+    i.raise_exception (E_inval, "trailing data");
 
   return res;
 };
-- 
2.39.1