exploration.utils

  1"""
  2- Authors: Peter Mawhorter
  3- Consulted:
  4- Date: 2023-12-29
  5- Purpose: Utility functions with no specific relevance to particular
  6    sub-systems.
  7
  8"""
  9
 10from typing import Collection, Optional, Tuple
 11
 12import random
 13
 14#-------------------#
 15# Utility functions #
 16#-------------------#
 17
 18RANDOM_NAME_SUFFIXES = False
 19"""
 20Causes `uniqueName` to use random suffixes instead of sequential ones,
 21which is more efficient when many name collisions are expected but which
 22makes things harder to test and debug. False by default.
 23"""
 24
 25
 26def uniqueName(base: str, existing: Collection) -> str:
 27    """
 28    Finds a unique name relative to a collection of existing names,
 29    using the given base name, plus a unique suffix if that base name is
 30    among the existing names. If the base name isn't among the existing
 31    names, just returns the base name. The suffix consists of a period
 32    followed by a number, and the lowest unused number is used every
 33    time. This does lead to poor performance in cases where many
 34    collisions are expected; you can set `RANDOM_NAME_SUFFIXES` to True
 35    to use a random suffix instead.
 36
 37    Note that if the base name already has a numerical suffix, that
 38    suffix will be changed instead of adding another one.
 39    """
 40    # Short-circuit if we're already unique
 41    if base not in existing:
 42        return base
 43
 44    # Ensure a digit suffix
 45    if (
 46        '.' not in base
 47     or not base.split('.')[-1].isdigit()
 48    ):
 49        base += '.1'
 50
 51    # Find the split point for the suffix
 52    # This will be the index after the '.'
 53    splitPoint = len(base) - list(reversed(base)).index('.')
 54    if not RANDOM_NAME_SUFFIXES:
 55        suffix = int(base[splitPoint:])
 56
 57    while base in existing:
 58        if RANDOM_NAME_SUFFIXES:
 59            base = base[:splitPoint] + str(random.randint(0, 1000000))
 60        else:
 61            suffix += 1
 62            base = base[:splitPoint] + str(suffix)
 63
 64    return base
 65
 66
 67ABBR_SYMBOLS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
 68"""
 69The list of symbols to use, in order, for abbreviations, adding
 70secondary symbols when the initial list runs out. It's stored as a
 71string, since each item is just one letter.
 72"""
 73
 74
 75def nextAbbrKey(currentKey: Optional[str]) -> str:
 76    """
 77    Given an abbreviation keys, returns the next abbreviation key after
 78    that. Abbreviation keys are constructed using the `ABBR_SYMBOLS` as
 79    a base. If the argument is `None`, the first of the `ABBR_SYMBOLS`
 80    will be returned. For example:
 81
 82    >>> nextAbbrKey(None)
 83    'A'
 84    >>> nextAbbrKey('A')
 85    'B'
 86    >>> nextAbbrKey('P')
 87    'Q'
 88    >>> nextAbbrKey('Z')
 89    'AA'
 90    >>> nextAbbrKey('AZ')
 91    'BA'
 92    >>> nextAbbrKey('BM')
 93    'BN'
 94    >>> nextAbbrKey('ZZ')
 95    'AAA'
 96    >>> nextAbbrKey('ZZZZ')
 97    'AAAAA'
 98    """
 99    if currentKey is None:
100        return ABBR_SYMBOLS[0]
101    else:
102        digits = [ABBR_SYMBOLS.index(c) for c in currentKey]
103        limit = len(ABBR_SYMBOLS)
104        digits[-1] += 1
105        i = -1
106        while digits[i] >= limit:
107            digits[i] = 0
108            try:
109                digits[i - 1] += 1
110                i -= 1
111            except IndexError:  # Overflow into a non-existent digit
112                digits.insert(0, 0)
113                break
114        return ''.join(ABBR_SYMBOLS[d] for d in digits)
115
116
117def abbr(string: str, length: int = 4) -> str:
118    """
119    Returns an abbreviated version of the given string, using at most
120    the given number of characters. Creates two alternatives: a
121    version without non-alphanumerics, and a version without
122    non-alphanumerics or vowels (except an initial vowel). If the entire
123    string fits in the given length, it just returns that. If not, and
124    the version with just alphanumerics fits in the given length, or
125    the version without vowels is shorter than necessary, returns the
126    version with just alphanumerics, up to the given length. Otherwise,
127    returns the alphanumeric version without non-initial vowels.
128    Examples:
129
130    >>> abbr('abc')
131    'abc'
132    >>> abbr('abcdefgh')
133    'abcd'
134    >>> abbr('aeiou')
135    'aeio'
136    >>> abbr('axyzeiou')
137    'axyz'
138    >>> abbr('aeiouxyz')
139    'axyz'
140    >>> abbr('AEIOUXYZ')
141    'AXYZ'
142    >>> abbr('-hi-')  # fits
143    '-hi-'
144    >>> abbr('--hi--')  # doesn't fit
145    'hi'
146    >>> abbr('A to wa')
147    'Atow'
148    >>> abbr('A to wor')
149    'Atwr'
150    """
151    # Three results: all characters, all alphanumerics, and all
152    # non-vowel alphanumerics (up to the given length + initial vowel)
153    result1 = ''
154    result2 = ''
155    index = 0
156    while index < len(string) and len(result1) < length:
157        c = string[index]
158        if not c.isalnum():
159            pass
160        elif c.lower() in 'aeiou' and index > 0:
161            result2 += c
162        else:
163            result1 += c
164            result2 += c
165        index += 1
166
167    # Use ~ least restricted result that's short enough
168    if len(string) <= length:
169        return string
170    elif len(result2) <= length or len(result1) < length:
171        return result2[:length]
172    else:
173        return result1
174
175
176def quoted(string: str) -> str:
177    """
178    Returns a string that starts and ends with double quotes, which will
179    evaluate to the given string using `eval`. Adds a layer of
180    backslashes before any backslashes and/or double quotes in the
181    original string. Different from `repr` because it always uses double
182    quotes. Raises a `ValueError` if given a multi-line string because
183    multi-line strings cannot be properly quoted using just a single
184    pair of double quotes.
185
186    >>> quoted('1\\n2')
187    Traceback (most recent call last):
188    ...
189    ValueError...
190    >>> quoted('12')
191    '"12"'
192    >>> quoted('back\\\\slash')
193    '"back\\\\\\\\slash"'
194    >>> quoted('"Yes!" she said, "it\\'s finished."')
195    '"\\\\"Yes!\\\\" she said, \\\\"it\\'s finished.\\\\""'
196    """
197    if '\n' in string:
198        raise ValueError("Cannot quote a multi-line string.")
199
200    return '"' + string.translate({ord('"'): '\\"', ord('\\'): '\\\\'}) + '"'
201
202
203def unquoted(startsQuoted: str) -> Tuple[str, str]:
204    """
205    Inverse of `quoted`: takes a string starting with a double quote,
206    and returns the string which got quoted to become that (plus the
207    leftovers after the quoted region). Parses out where the quotes end
208    automatically and accumulates as leftovers any extra part of the
209    string beyond that. Removes one layer of backslashes from
210    everything. Raises a `ValueError` if the string does not start with
211    a double quote or if it does not contain a matching double quote
212    eventually.
213
214    For example:
215
216    >>> unquoted('abc')
217    Traceback (most recent call last):
218    ...
219    ValueError...
220    >>> unquoted('"abc')
221    Traceback (most recent call last):
222    ...
223    ValueError...
224    >>> unquoted('"abc"')
225    ('abc', '')
226    >>> unquoted('"a" = "b"')
227    ('a', ' = "b"')
228    >>> unquoted('"abc" extra')
229    ('abc', ' extra')
230    >>> unquoted('"abc" "extra"')
231    ('abc', ' "extra"')
232    >>> unquoted('"\\\\"abc\\\\""')
233    ('"abc"', '')
234    >>> unquoted('"back\\\\\\\\slash"')
235    ('back\\\\slash', '')
236    >>> unquoted('"O\\'Toole"')
237    ("O'Toole", '')
238    >>> unquoted('"\\\\"Yes!\\\\" she said, \\\\"it\\'s finished!\\\\""')
239    ('"Yes!" she said, "it\\'s finished!"', '')
240    >>> quoted(unquoted('"\\'"')[0]) == '"\\'"'
241    True
242    >>> unquoted(quoted('"\\'"')) == ('"\\'"', '')
243    True
244    """
245    if not startsQuoted.startswith('"'):
246        raise ValueError(
247            f"No double-quote at start of string: '{startsQuoted}'"
248        )
249    result = ''
250    leftovers = ''
251    finished = False
252    escaped = False
253    if not startsQuoted.startswith('"'):
254        raise ValueError(
255            f"No starting double quote in string: {repr(startsQuoted)}"
256        )
257    for c in startsQuoted[1:]:
258        if finished:
259            leftovers += c
260        elif escaped:
261            escaped = False
262            result += c
263        elif c == '\\':
264            escaped = True
265        elif c == '"':
266            finished = True
267        else:
268            result += c
269    if not finished:
270        raise ValueError(
271            f"No matching double-quote to end string: {repr(startsQuoted)}"
272        )
273    else:
274        return result, leftovers