Add doctests

Author: rocky

Makefile

@@ -37,8 +37,12 @@ pypi-setup:
 develop: pypi-setup
 	$(PIP) install -e .
 
+doctest:
+	MATHICS_CHARACTER_ENCODING="ASCII" $(PYTHON) -m mathics.docpipeline -l pymathics.icu -c 'ICU — International Components for Unicode' $o
+
+
 # Run tests
-check: pytest
+check: pytest doctest
 
 #: Remove derived files
 clean: clean-pyc

pymathics/icu/__init__.py

@@ -7,11 +7,11 @@
 
   Load in Mathics3 Module:
   >> LoadModule["pymathics.icu"]
-    = pymathics.natlang
+    = pymathics.icu
 
   Show the language in effect:
   >> $Language
-   = "English"
+   = English
 
   Get the alphabet for that language:
   >> Alphabet[]
@@ -26,7 +26,7 @@
    = {ʼ, а, б, в, г, д, е, ж, з, и, й, к, л, м, н, о, п, р, с, т, у, ф, х, ц, ч, ш, щ, ь, ю, я, є, і, ї, ґ}
 """
 
-from pymathics.icu.__main__ import Alphabet, Language
+from pymathics.icu.__main__ import Alphabet, AlphabeticOrder, Language
 from pymathics.icu.version import __version__
 
 pymathics_version_data = {
@@ -36,4 +36,4 @@
     "requires": ["PyICU"],
 }
 
-__all__ = ["Alphabet", "Language", "pymathics_version_data", "__version__"]
+__all__ = ["Alphabet", "AlphabeticOrder", "Language", "pymathics_version_data", "__version__"]

pymathics/icu/__main__.py

@@ -4,38 +4,81 @@
 Languages - Human-Language Alphabets and Locales via PyICU.
 """
 
-# PYTHON MODULES USED IN HERE
-
-# PyICU: human-language alphabets and locales
-
-
 from typing import List, Optional
 
-from icu import Locale, LocaleData
-from mathics.core.atoms import String
+from icu import Collator, Locale, LocaleData
+from mathics.core.atoms import Integer, String
 from mathics.core.builtin import Builtin, Predefined
 from mathics.core.convert.expression import to_mathics_list
 from mathics.core.evaluation import Evaluation
 
-availableLocales = Locale.getAvailableLocales()
+available_locales = Locale.getAvailableLocales()
 language2locale = {
     availableLocale.getDisplayLanguage(): locale_name
-    for locale_name, availableLocale in availableLocales.items()
+    for locale_name, availableLocale in available_locales.items()
 }
 
 # The current value of $Language
 LANGUAGE = "English"
 
+
 def eval_alphabet(language_name: String) -> Optional[List[String]]:
 
     py_language_name = language_name.value
     locale = language2locale.get(py_language_name, py_language_name)
-    if locale not in availableLocales:
+    if locale not in available_locales:
         return
     alphabet_set = LocaleData(locale).getExemplarSet(0, 0)
     return to_mathics_list(*alphabet_set, elements_conversion_fn=String)
 
 
+def eval_alphabetic_order(string1: str, string2: str, language_name=LANGUAGE) -> int:
+    """
+    Compare two strings using locale-sensitive alphabetic order.
+
+    Returns:
+        1 if string1 appears before string2 in alphabetic order,
+        -1 if string1 appears after string2,
+        0 if they are identical.
+    """
+    locale_str = language_to_locale(language_name)
+    collator = Collator.createInstance(Locale(locale_str))
+    comparison = collator.compare(string1, string2)
+    if comparison < 0:
+        return 1
+    elif comparison > 0:
+        return -1
+    else:
+        return 0
+
+
+def language_to_locale(language_name: str, fallback="en_US") -> str:
+    """
+    Convert a language name (e.g., "English") to an ICU locale string (e.g., "en_US").
+    Returns the first matching locale string or a fallback if not found.
+
+    Args:
+        language_name (str): Language name in English (e.g., "English", "French").
+        fallback (str): Locale string to return if not found.
+
+    Returns:
+        str: Locale string (e.g., "en_US", "fr_FR").
+    """
+    # Normalize input
+    language_name = language_name.strip().lower()
+
+    for loc_str in available_locales:
+        loc = Locale(loc_str)
+        # Get display language in English.
+        # FIXME? Generalize or do better later?
+        disp_lang = loc.getDisplayLanguage(Locale("en")).lower()
+        if disp_lang == language_name:
+            return loc_str
+
+    # Could not find exact match, return fallback
+    return fallback
+
+
 class Alphabet(Builtin):
     """
      Basic lowercase alphabet via <url>:Unicode: https://home.unicode.org/</url> and <url>:PyICU: https://pypi.org/project/PyICU/</url>
@@ -48,7 +91,7 @@ class Alphabet(Builtin):
     </dl>
 
     >> Alphabet["Ukrainian"]
-     = {a, ä, b, c, d, e, f, g, h, i, j, k, l, m, n, o, ö, p, q, r, s, ß, t, u, ü, v, w, x, y, z}
+     = {ʼ, а, б, в, г, д, е, ж, з, и, й, к, л, м, н, о, п, р, с, т, у, ф, х, ц, ч, ш, щ, ь, ю, я, є, і, ї, ґ}
 
     The alphabet when nothing is specified, "English" is used:
     >> Alphabet[]
@@ -81,6 +124,48 @@ def eval(self, alpha: String, evaluation):
             return
         return alphabet_list
 
+
+class AlphabeticOrder(Builtin):
+    """
+     <url>:WMA:https://reference.wolfram.com/language/ref/AlphabeticOrder.html</url>
+     <dl>
+      <dt>'AlphabetOrder'[$string_1$, $string_2$]
+      <dd>gives 1 if $string_1$ appears before $string_2$ in alphabetical order, -1 if it is after, and 0 if it is identical.
+    </dl>
+
+     >> AlphabeticOrder["apple", "banana"]
+      = 1
+
+     >> AlphabeticOrder["parrot", "parrot"]
+      = 0
+
+     When words are the same but only differ in case, usually lowercase letters come first:
+     >> AlphabeticOrder["A", "a"]
+      = -1
+
+     Longer words follow their prefixes:
+     >> AlphabeticOrder["Papagayo", "Papa", "Spanish"]
+      = -1
+
+     But accented letters usually appear at the end of the alphabet:
+     >> AlphabeticOrder["Papá", "Papa", "Spanish"]
+      = -1
+
+     >> AlphabeticOrder["Papá", "Papagayo", "Spanish"]
+      = 1
+    """
+
+    summary_text = "compare strings according to an alphabet"
+
+    def eval(self, string1: String, string2: String, evaluation: Evaluation):
+        """AlphabeticOrder[string1_String, string2_String]"""
+        return Integer(eval_alphabetic_order(string1.value, string2.value))
+
+    def eval_with_lang(self, string1: String, string2: String, lang: String, evaluation: Evaluation):
+        """AlphabeticOrder[string1_String, string2_String, lang_String]"""
+        return Integer(eval_alphabetic_order(string1.value, string2.value, lang.value, ))
+
+
 ## FIXME: move to mathics-core. Will have to change references to Pymathics`$Language to $Language
 class Language(Predefined):
     """
@@ -95,15 +180,13 @@ class Language(Predefined):
 
     See the language in effect used for functions like 'Alphabet[]':
 
-    >> old_language = $Language
-     = ...
-
     By setting its value, The letters of 'Alphabet[]' are changed:
 
     >> $Language = "German"; Alphabet[]
      = ...
 
-    #> $Language = old_language;
+    #> $Language = "English"
+     = English
 
     See also <url>
     :Alphabet:

test/test_basic.py

@@ -1,11 +1,13 @@
 # -*- coding: utf-8 -*-
 
+from mathics.core.atoms import String
 from mathics.core.load_builtin import import_and_load_builtins
 from mathics.session import MathicsSession
 
 import_and_load_builtins()
 
 session = MathicsSession(character_encoding="UTF-8")
+assert session.evaluate('LoadModule["pymathics.icu"]') == String("pymathics.icu")
 
 
 def check_evaluation(str_expr: str, expected: str, assert_message=""):
@@ -19,8 +21,7 @@ def check_evaluation(str_expr: str, expected: str, assert_message=""):
         assert result == expected
 
 
-def test_language():
-    session.evaluate('LoadModule["pymathics.icu"]') == "pymathics.icu"
+def test_alphabet():
     check_evaluation(
         'Alphabet["es"]',
         (