Revise to fit better inside previous fileformats frameworks.

rocky · rocky · commit 5dbe72d4801b · 2026-06-27T18:17:12.000-04:00
(I wasn't aware of this work until late on.)
diff --git a/SYMBOLS_MANIFEST.txt b/SYMBOLS_MANIFEST.txt
@@ -1,3 +1,4 @@
+Compress`ImportZIP
 HTML`DataImport
 HTML`FullDataImport
 HTML`HyperlinksImport
@@ -12,7 +13,7 @@ ImportExport`RegisterExport
 ImportExport`RegisterImport
 Internal`RealValuedNumberQ
 Internal`RealValuedNumericQ
-JSON`Import`JSONImport
+JSON`ImportJSON
 System`$Aborted
 System`$Assumptions
 System`$BaseDirectory
@@ -582,9 +583,7 @@ System`ImageTake
 System`ImageType
 System`Implies
 System`Import
-System`ImportJSON
 System`ImportString
-System`ImportZIP
 System`In
 System`Increment
 System`Indeterminate
diff --git a/mathics/SystemFiles/Formats/JSON/Import.wl b/mathics/SystemFiles/Formats/JSON/Import.wl
@@ -1,15 +1,19 @@
 (* ::Package:: *)
 
+(* JSON Javascript Object Notation or JSON web service description Importer.
+   This is used by Import[] and, ImportString[].
+ *)
+
 Begin["System`Convert`JSONDump`"]
 
 (* JSON legacy element is Data even if Expression would be better. *)
 $AvailableElements = {"Data", "Dataset"};
 
 ImportExport`RegisterImport[
-    "JSON",
-    ImportJSON,
+    "JSON",  (* WMA mime-type name *)
+    JSON`ImportJSON, (* Default Function name that handles this. *)
     {},
-    "AvailableElements" -> $AvailableElements,
+    "AvailableElements" -> $AvailableElements, (* names retuned by "Elements" query *)
     "FunctionChannels" -> {"FileNames"},
     "DefaultElement" -> "Data"
 ]
diff --git a/mathics/SystemFiles/Formats/ZIP/Import.wl b/mathics/SystemFiles/Formats/ZIP/Import.wl
@@ -1,7 +1,7 @@
 (* ::Package:: *)
 
-(* ZIP compressed file and file archive Importer.
-   This is used by Import[].
+(* Windows ZIP archive, ZIP compressed file and file archive Importer.
+   This is used by Import[] and, ImportString[].
  *)
 
 Begin["System`Convert`CommonArchiveDump`"]
@@ -21,13 +21,13 @@ GetElements[___] :=
 		];
 
 ImportExport`RegisterImport[
-    "ZIP",
-    ImportZIP,
+    "ZIP", (* WMA mime-type name *)
+    Compress`ImportZIP,  (* Default Function name that handles this. *)
     {}, (* Post importer function(s) *)
     FunctionChannels -> {"FileNames"},
     (* WMA has this, but I (rocky) am not sure why or what it means:
     AvailableElements -> $ZIPAvailableElements, *)
-    AvailableElements -> {"Filenames", "Summary"},
+    AvailableElements -> {"Filenames", "Summary"},  (* names retuned by "Elements" query *)
     BinaryFormat -> True,
     DefaultElement -> "FileNames",
     HiddenElements -> $ZIPHiddenElements,
diff --git a/mathics/builtin/fileformats/__init__.py b/mathics/builtin/fileformats/__init__.py
@@ -1,10 +1,12 @@
 """
-File Formats
+Import/Export File Formats
 
-Built-in Importers.
+There various file formats can be used by 'Import' and 'Export' and related functions, \
+e.g. 'ImportString'.
 
-"""
+Many Import/Export functions are registered in SystemFiles/Formats/*.wl which is \
+autoloaded on startup.
 
-# The Built-in Functions are defined in a separate context under the
-# System`. For example System`HTML` and System`XML.  This is done to not
-# pollute the System` namespace.
+The Built-in Functions are defined in a separate context.
+For example, HTML` or Compress`.  This is done to not pollute the System` namespace.
+"""
diff --git a/mathics/builtin/fileformats/compression.py b/mathics/builtin/fileformats/compression.py
@@ -0,0 +1,32 @@
+"""
+Compression & Archive Formats
+"""
+
+from mathics.core.builtin import Builtin, String
+from mathics.core.evaluation import Evaluation
+from mathics.eval.fileformats.compression import eval_ImportZIP
+
+# See commit in __init__.py regarding the whacky way this gets called
+
+
+class ImportZIP(Builtin):
+    """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/format/ZIP.html</url>
+
+    <dl>
+      <dt>'Compress`ImportZIP[path]'
+      <dd>Run zip for archive file $path$
+    </dl>
+
+    """
+
+    context = "Compress`"
+    summary_text = "import a ZIP file"
+
+    def eval(self, path: String, evaluation: Evaluation):
+        "Compress`ImportZIP[path_String]"
+        return eval_ImportZIP(path, evaluation)
+
+    def eval_with_elements(self, path: String, elements, evaluation: Evaluation):
+        "Compress`ImportZIP[path_String, elements_]"
+        return eval_ImportZIP(path, evaluation, elements)
diff --git a/mathics/builtin/fileformats/htmlformat.py b/mathics/builtin/fileformats/htmlformat.py
@@ -2,7 +2,7 @@
 """
 HTML
 
-Basic implementation for a HTML importer.
+HTML importer.
 """
 
 
diff --git a/mathics/builtin/fileformats/jsonformat.py b/mathics/builtin/fileformats/jsonformat.py
@@ -1,32 +1,29 @@
-# -*- coding: utf-8 -*-
-
 """
-JSON
+JSON File Format
 
-Basic implementation for an JSON importer.
+JSON importer (via Python's "json" module).
 """
 
-from mathics.core.builtin import Builtin
-from mathics.core.expression import Evaluation
-from mathics.eval.fileformats.jsonformat import eval_JSONImport
+from mathics.core.builtin import Builtin, String
+from mathics.core.evaluation import Evaluation
+from mathics.eval.fileformats.json import eval_JSONImport
 
 
-class JSONImport(Builtin):
+class ImportJSON(Builtin):
     """
-    ## <url>:native internal:</url>
+    <url>:WMA link:https://reference.wolfram.com/language/ref/format/JSON.html</url>
 
     <dl>
-      <dt>'JSON`Import`JSONImport["file"]'
-      <dd>parses "string" as a JSON file, and returns the data as a nested \
-          list of rules.
+      <dt>'JSON`ImportJSON[path]'
+      <dd>Read $path$ as JSON and convert that to its corresponding Mathics3 equivalent.
     </dl>
 
     """
 
-    summary_text = "import elements from json"
-    context = "JSON`Import`"
+    context = "JSON`"
     messages = {"dec": "Decoding Error at `1`"}
+    summary_text = "import JSON file"
 
-    def eval(self, filename, evaluation: Evaluation):
-        """%(name)s[filename_String]"""
-        return eval_JSONImport(filename.value, evaluation)
+    def eval(self, path: String, evaluation: Evaluation):
+        "JSON`ImportJSON[path_String]"
+        return eval_JSONImport(path, evaluation)
diff --git a/mathics/builtin/fileformats/xmlformat.py b/mathics/builtin/fileformats/xmlformat.py
@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 
 """
-XML
+XML File Format
 
-Basic implementation for an XML importer.
+XML importer (via lxml).
 """
 
 
diff --git a/mathics/builtin/import_export/compression.py b/mathics/builtin/import_export/compression.py
diff --git a/mathics/builtin/import_export/json.py b/mathics/builtin/import_export/json.py
diff --git a/mathics/eval/fileformats/compression.py b/mathics/eval/fileformats/compression.py
@@ -8,6 +8,7 @@
 from mathics.core.list import ListExpression
 from mathics.core.symbols import SymbolNull
 from mathics.core.systemsymbols import SymbolFailed, SymbolRule
+from mathics.eval.files_io.files import resolve_file
 from mathics.eval.import_export.importexport import (
     IMPORTERS,
     eval_Import_data_only,
@@ -16,13 +17,20 @@
 
 
 def eval_ImportZIP(
-    zip_path: str, evaluation: Evaluation, members: Optional[list[str]] = None
+    zip_name: String, evaluation: Evaluation, members: Optional[list[str]] = None
 ) -> ListExpression:
     """If `members` is empty, this function takes a ZIP file path and returns a
     list of file names/paths contained inside.
 
     "If `members` is given, then extract those members from the ZIP file.
     """
+
+    zip_path, is_temporary_file = resolve_file(zip_name, "r", evaluation)
+    if zip_path is None:
+        return SymbolFailed
+
+    # The below "try:" is probably unnecessary since resolve_file should
+    # catch errors.
     try:
         with zipfile.ZipFile(zip_path, "r") as archive:
             if members is None:
diff --git a/mathics/eval/fileformats/json.py b/mathics/eval/fileformats/json.py
@@ -0,0 +1,39 @@
+import json
+
+from mathics.core.atoms import String
+from mathics.core.convert.python import from_python
+from mathics.core.expression import Evaluation, Expression
+from mathics.core.list import ListExpression
+from mathics.core.systemsymbols import SymbolFailed, SymbolRule
+from mathics.eval.files_io.files import resolve_file
+
+
+def eval_JSONImport(json_name: String, evaluation: Evaluation) -> ListExpression:
+    """Takes a JSON file path and returns a list of file names/paths contained inside."""
+    json_path, is_temporary_file = resolve_file(json_name, "r", evaluation)
+    if json_path is None:
+        return SymbolFailed
+
+    with open(json_path, "r") as json_file:
+        try:
+            json_data = json.load(json_file)
+        except json.decoder.JSONDecodeError as exc:
+            evaluation.message("JSON`Import`JSONImport", "dec", String(exc.msg))
+            return None
+        mathics_json = from_python(json_data)
+
+        # Tag the result by wrapping in a list of rule expressions.
+        # We do this so that Import can extract pieces by element name.
+        exprs = [
+            Expression(
+                SymbolRule,
+                String("Data"),
+                mathics_json,
+            ),
+            Expression(
+                SymbolRule,
+                String("Dataset"),
+                mathics_json,
+            ),
+        ]
+        return ListExpression(*exprs)
diff --git a/mathics/eval/fileformats/jsonformat.py b/mathics/eval/fileformats/jsonformat.py
diff --git a/mathics/eval/files_io/files.py b/mathics/eval/files_io/files.py
@@ -235,14 +235,9 @@ def eval_Open(
     encoding: Optional[str],
     evaluation: Evaluation,
 ):
-    path = name.value
-    tmp, is_temporary_file = path_search(path)
-    if tmp is None:
-        if mode in ["r", "rb"]:
-            evaluation.message("General", "noopen", name)
-            return SymbolFailed
-    else:
-        path = tmp
+    path, is_temporary_file = resolve_file(name, mode, evaluation)
+    if path is None:
+        return SymbolFailed
 
     try:
         opener = Mathics3Open(
@@ -426,3 +421,25 @@ def eval_Read(
                     return Expression(SymbolHold, from_python(result))
 
     return from_python(result)
+
+
+def resolve_file(name: String, mode: str, evaluation: Evaluation) -> Optional[str]:
+    """Resolve 'name' using `path_search` and returned the resolved name as the first
+    item of a tuple.
+
+    If "mode" a write mode, then the file does not have to exist beforehand.
+    In some cases `path_search()` will decide that a temporary file is to be
+    created. In this case that fact will be reflected by returning True as the
+    second item of the tuple.
+
+    If we can't open the file, we emit a "noopen" message.
+    """
+    path = name.value
+    resolved_path, is_temporary_file = path_search(path)
+    if resolved_path is None:
+        if mode in ["r", "rb"]:
+            evaluation.message("General", "noopen", name)
+            return None, False
+        resolved_path = path
+
+    return resolved_path, is_temporary_file
diff --git a/mathics/eval/import_export/importexport.py b/mathics/eval/import_export/importexport.py
diff --git a/mathics/eval/import_export/json.py b/mathics/eval/import_export/json.py
