words: parse_relations -> parse

Author: Joseph-Edwards

docs/source/data-structures/words/index.rst

@@ -31,7 +31,7 @@ This pages contains links to documentation in ``libsemigroups_pybind11`` for:
 
 - parsing algebraic expressions in a string;
 
-  - :any:`parse_relations`
+  - :any:`parse`
 
 .. toctree::
     :maxdepth: 1

docs/source/data-structures/words/word-funcs.rst

@@ -39,6 +39,7 @@ Contents
 
      human_readable_index
      human_readable_letter
+     parse
      parse_relations
      pow
      prod

src/libsemigroups_pybind11/words.py

@@ -12,9 +12,17 @@
 from _libsemigroups_pybind11 import (  # pylint: disable=redefined-builtin
     words_human_readable_index as human_readable_index,
     words_human_readable_letter as human_readable_letter,
+    words_parse as parse,
     words_parse_relations as parse_relations,
     words_pow as pow,
     words_prod as prod,
 )
 
-__all__ = ["human_readable_index", "human_readable_letter", "parse_relations", "pow", "prod"]
+__all__ = [
+    "human_readable_index",
+    "human_readable_letter",
+    "parse",
+    "parse_relations",
+    "pow",
+    "prod",
+]

src/word-range.cpp

@@ -33,6 +33,7 @@
 
 // pybind11....
 #include <pybind11/complex.h>
+#include <pybind11/eval.h>      // for pybind11::exec
 #include <pybind11/pybind11.h>  // for make_iterator, module
 #include <pybind11/stl.h>
 
@@ -1354,7 +1355,55 @@ in the range ``[min, max)`` over the specified alphabet.
     // Helper functions for words in words namespace
     ////////////////////////////////////////////////////////////////////////////
 
-    m.def("words_parse_relations",
+    m.def(
+        "words_parse_relations",
+        [](char const* w) {
+          py::exec(R"(
+            from warnings import warn
+
+            warn(
+               "words.parse_relations is deprecated, and will be removed from libsemigroups_pybind11 in v2. Instead, use words.parse",
+               DeprecationWarning,
+               2
+            )
+            )");
+          return literals::operator""_p(w);
+        },
+        py::arg("w"),
+        R"pbdoc(
+:sig=(w: str) -> str:
+Construct string by parsing an algebraic expression.
+
+This function provides a means of constructing a :any:`str` from an algebraic
+expression, and has the following behaviour:
+
+* arbitrarily nested brackets;
+* spaces are ignored;
+* redundant matched brackets are ignored;
+* only the characters in ``"()^ "`` and in ``a-zA-Z0-9`` are allowed.
+
+:param w: the expression to parse.
+:type w: str
+
+:returns: The parsed expression.
+:rtype: str
+
+:raises LibsemigroupsError: if *w* cannot be parsed.
+
+.. doctest::
+
+  >>> from libsemigroups_pybind11.words import parse_relations
+  >>> parse_relations("((ab)^3cc)^2")
+  'abababccabababcc'
+  >>> parse_relations("a^0")
+  ''
+
+.. deprecated:: 1.5
+  This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use
+  :any:`words.parse`.
+)pbdoc");
+
+    m.def("words_parse",
           py::overload_cast<char const*>(&literals::operator""_p),
           py::arg("w"),
           R"pbdoc(
@@ -1363,6 +1412,7 @@ Construct string by parsing an algebraic expression.
 
 This function provides a means of constructing a :any:`str` from an algebraic
 expression, and has the following behaviour:
+
 * arbitrarily nested brackets;
 * spaces are ignored;
 * redundant matched brackets are ignored;

tests/test_word_range.py

@@ -22,11 +22,7 @@
     random_strings,
     random_word,
 )
-from libsemigroups_pybind11.words import (
-    human_readable_index,
-    human_readable_letter,
-    parse_relations,
-)
+from libsemigroups_pybind11.words import human_readable_index, human_readable_letter, parse
 
 
 def test_number_of_words():
@@ -231,31 +227,28 @@ def test_StringRange_000():
     ]
 
 
-def test_parse_relations():
-    assert parse_relations("cd(ab)^2ef") == "cdababef"
-    assert parse_relations("cd((ab)^2)^4ef") == "cdababababababababef"
-    assert parse_relations("cd((ab)^2)^4(ef)^2") == "cdababababababababefef"
-    assert parse_relations("a^16") == "aaaaaaaaaaaaaaaa"
-    assert (
-        parse_relations("a^16cd^10((ab)^2)^4(ef)^2")
-        == "aaaaaaaaaaaaaaaacddddddddddababababababababefef"
-    )
-    assert parse_relations("X^3(yx^2)") == "XXXyxx"
-    assert parse_relations("b(aX)^3x") == "baXaXaXx"
-    assert parse_relations("((a)b^2y)^10") == "abbyabbyabbyabbyabbyabbyabbyabbyabbyabby"
+def test_parse():
+    assert parse("cd(ab)^2ef") == "cdababef"
+    assert parse("cd((ab)^2)^4ef") == "cdababababababababef"
+    assert parse("cd((ab)^2)^4(ef)^2") == "cdababababababababefef"
+    assert parse("a^16") == "aaaaaaaaaaaaaaaa"
+    assert parse("a^16cd^10((ab)^2)^4(ef)^2") == "aaaaaaaaaaaaaaaacddddddddddababababababababefef"
+    assert parse("X^3(yx^2)") == "XXXyxx"
+    assert parse("b(aX)^3x") == "baXaXaXx"
+    assert parse("((a)b^2y)^10") == "abbyabbyabbyabbyabbyabbyabbyabbyabbyabby"
 
-    assert parse_relations("()") == ""
-    assert parse_relations("y^0") == ""
-    assert parse_relations("") == ""
-    assert parse_relations("a") == "a"
+    assert parse("()") == ""
+    assert parse("y^0") == ""
+    assert parse("") == ""
+    assert parse("a") == "a"
 
-    assert parse_relations("           ") == ""
+    assert parse("           ") == ""
 
 
 def test_ToWord_1():
     to_word = ToWord()
-    assert to_word(parse_relations("cd(ab)^2ef")) == [2, 3, 0, 1, 0, 1, 4, 5]
-    assert to_word(parse_relations("cd((ab)^2)^4ef")) == [
+    assert to_word(parse("cd(ab)^2ef")) == [2, 3, 0, 1, 0, 1, 4, 5]
+    assert to_word(parse("cd((ab)^2)^4ef")) == [
         2,
         3,
         0,
@@ -277,7 +270,7 @@ def test_ToWord_1():
         4,
         5,
     ]
-    assert to_word(parse_relations("cd((ab)^2)^4(ef)^2")) == [
+    assert to_word(parse("cd((ab)^2)^4(ef)^2")) == [
         2,
         3,
         0,