# ==============================================================================
# array_utils.nm - Tony Balinski
#
# This file contains NEdit macro utility functions
#
#       make_array_from_list
#       make_array
#       make_arraylist
#       make_arraylist1
#       shift_arraylist
#       array_has_value
#       cat_arraylist
#       cat_arraylist1
#       arrayval_10ask
#       array_ask_keys
#       array_ask_vals
#       array_select_entry
# ==============================================================================

NEDIT_require_macro_file("extensions.nm")

# ==============================================================================
# make_array_from_list(list_array[, start]): builds an array from the key-value
#       pairs from contiguous values in list_array, and returns it. The keys to
#       list_array must be consecutive numbers, starting with start (or zero).
#       There must be an even number of them.
# ==============================================================================

define make_array_from_list
  {
  list_array = $1
  start = 0
  if ($n_args > 1)
    start = $2

  array = $empty_array

  # now add to array until we have no more elements in list_array[]
  for (i = start; i in list_array; i += 2)
    {
    key = list_array[i]
    val = list_array[i + 1]
    array[key] = val
    }

  return array
  }

# ==============================================================================
# make_array(key, value, ...): builds an array from the key-value pairs, and
#       returns it. If an odd number of arguments is given, does not return
#       anything, which should cause an error.
# ==============================================================================

define make_array
  {
  return make_array_from_list($args, 1)
  }

# ==============================================================================
# make_arraylist(value, ...): builds an array from the values, using numeric
#       indices starting at zero, and returns it.
# ==============================================================================

define make_arraylist
  {
  # prepare the array (results in an empty array if $args[] == 0)
  if ($args[] == 0)
    return $args

  array = $empty_array
  # copy $args[] to array[], starting at index 0
  for (i = 0; i < $args[]; i++)
    {
    array[i] = $args[i + 1]
    }

  return array
  }

# ==============================================================================
# make_arraylist1(value, ...): builds an array from the values, using numeric
#       indices starting at one, and returns it.
# ==============================================================================

define make_arraylist1
  {
  return $args
  }

# ==============================================================================
# shift_arraylist(offset, oldarray [, low, high]): builds an array from the
#       values in oldarray (accessed through numeric indices): the new array has
#       indices shifted by offset compared to the old, and if low and high
#       are given, only those new indices from low to high are kept.
# ==============================================================================

define shift_arraylist
  {
  offset = $1
  oldarray = $2

  NaN = ":"
  lo = NaN
  hi = NaN

  if ($n_args > 2 && valid_number($3))
    lo = $3
  if ($n_args > 3 && valid_number($4))
    hi = $4

  if (oldarray[] == 0)
    return oldarray

  array = $empty_array

  for (k in oldarray)
    {
    if (!valid_number(k))
      continue
    i = k + offset
    ok = ((lo == NaN) || (lo <= i)) && ((hi == NaN) || (i < hi))
    if (ok)
      array[i] = oldarray[k]
    }

  return array
  }

# ==============================================================================
# array_has_value(array, value): determines whether array has an entry whose
#       value is that given. Returns an array of keys to the value, indexed by
#       number. This will be an empty array if value was not found.
# ==============================================================================

define array_has_value
  {
  array = $1
  value = $2
  res = make_array()

  i = 0
  for (key in array)
    if (array[key] == value)
      res[i++] = key

  return res
  }

# ==============================================================================
# cat_arraylist(array [, separator]): concatenates a zero-based array to a
#       string, adding the separator (default "\n") between each piece. Note
#       that separators are not added after the last entry. This is the
#       "opposite" of split - the following identity is true:
#
#           str == cat_arraylist(split(str, "\n"), "\n")
# ==============================================================================

define cat_arraylist
  {
  str = ""
  array = $1
  separator = "\n"
  if ($n_args > 1)
    separator = $2
  sep = ""

  for (i = 0; i in array; i++)
    {
    str = str sep array[i]
    sep = separator
    }

  return str
  }

# ==============================================================================
# cat_arraylist1(array [, separator]): concatenates a one-based array to a
#       string, adding the separator (default "\n") between each piece. Note
#       that separators are not added after the last entry.
# ==============================================================================

define cat_arraylist1
  {
  str = ""
  array = $1
  separator = "\n"
  if ($n_args > 1)
    separator = $2
  sep = ""

  for (i = 1; i in array; i++)
    {
    str = str sep array[i]
    sep = separator
    }

  return str
  }

# ==============================================================================
# match_arraykey_key(array, prefix [, match_t]): looks for a key that matches
#       prefix. If no match type is given, prefix is matched against each key
#       until a key that starts with prefix is found. If match_t is given, the
#       match must satisfy
#           search_string(key, prefix, 0, match_t) == 0
#       Returns the full key; fails with "".
# ==============================================================================

define match_arraykey_key
  {
  array = $1
  prefix = $2
  match_t = "case"
  if ($n_args >= 3)
    match_t = $3

  if (match_t == "case")
    if (prefix in array)
      return prefix

  for (key in array)
    if (search_string(key, prefix, 0, match_t) == 0)
      return key

  return ""
  }

# ==============================================================================
# match_arraykey_value(array, prefix [, match_t [, failval]]): looks for a key
#       that matches prefix. If no match type is given, prefix is matched
#       against each key until a key that starts with prefix is found. If
#       match_t is given, the match must satisfy
#           search_string(key, prefix, 0, match_t) == 0
#       Returns the value of the element with the key found; fails with "", or
#       failval if supplied.
# ==============================================================================

define match_arraykey_value
  {
  array = $1
  prefix = $2
  match_t = "case"
  if ($n_args >= 3)
    match_t = $3
  failval = ""
  if ($n_args >= 4)
    failval = $4

  key = match_arraykey_key(array, prefix, match_t)
  if (key == "")
    return failval

  return array[key]
  }

# ==============================================================================
# match_arrayval_key(array, prefix [, match_t]): looks for a value that matches
#       prefix. If no match type is given, prefix is matched against each value
#       until one that starts with prefix is found. If match_t is given, the
#       match must satisfy
#           search_string(value, prefix, 0, match_t) == 0
#       Returns the key to the element; fails with "". All elements must be
#       strings.
# ==============================================================================

define match_arrayval_key
  {
  array = $1
  prefix = $2
  match_t = "case"
  if ($n_args >= 3)
    match_t = $3

  for (key in array)
    if (search_string(array[key], prefix, 0, match_t) == 0)
      return key

  return ""
  }

# ==============================================================================
# match_arrayval_value(array, prefix [, match_t]): looks for a value that matches
#       prefix. If no match type is given, prefix is matched against each value
#       until one that starts with prefix is found. If match_t is given, the
#       match must satisfy
#           search_string(value, prefix, 0, match_t) == 0
#       Returns the complete value of the element with the key found; fails
#       with "".
# ==============================================================================

define match_arraykey_value
  {
  array = $1
  prefix = $2
  match_t = "case"
  if ($n_args >= 3)
    match_t = $3

  key = match_arrayval_key(array, prefix, match_t)
  if (key == "")
    return ""

  return array[key]
  }

# ==============================================================================
# arrayval_10ask(prompt, len, more, string_dlg, buttons [, lines]): asks for an
#       array value from a choice of up to 10 (as buttons), and/or a line.
#       buttons must be indexed from 0 to len - 1, and len must be less than 10.
#       If lines is present list_dialogs will be used. If string_dlg is false,
#       dialog will be used instead of string_dialog and ["line"] will not be
#       set. Uses an array return value with
#           ["more"]    ">>More" button pressed - ask for other ranges
#           ["null"]    dismissed - take no further action
#           ["button"]  the string for a button, or an entered string
#           ["line"]    the selected line or typed text, if any
#           ["index"]   the number of the button, if any
# ==============================================================================

define arrayval_10ask
  {
  prompt = $1
  len = $2
  more = $3
  string_dlg = $4
  buttons = $5
  use_list = 0
  lines = ""
  if ($n_args == 6)
    {
    use_list = 1
    lines = $6
    }

  c0 = ">>More"
  c1 = ">>More"
  c2 = ">>More"
  c3 = ">>More"
  c4 = ">>More"
  c5 = ">>More"
  c6 = ">>More"
  c7 = ">>More"
  c8 = ">>More"
  c9 = ">>More"
  cA = ">>More"

  ok = "OK"
  nok = "Cancel"

  if (len > 0) c0 = buttons[0]
  if (len > 1) c1 = buttons[1]
  if (len > 2) c2 = buttons[2]
  if (len > 3) c3 = buttons[3]
  if (len > 4) c4 = buttons[4]
  if (len > 5) c5 = buttons[5]
  if (len > 6) c6 = buttons[6]
  if (len > 7) c7 = buttons[7]
  if (len > 8) c8 = buttons[8]
  if (len > 9) c9 = buttons[9]

  if (more)
    len++

  if (use_list)
    {
    if (len == 0)
      {
      c = ""
      res = 0
      dismiss = 0
      }
    else if (len == 1)
      c = list_dialog(prompt, lines, c0, nok)
    else if (len == 2)
      c = list_dialog(prompt, lines, c0,c1, nok)
    else if (len == 3)
      c = list_dialog(prompt, lines, c0,c1,c2, nok)
    else if (len == 4)
      c = list_dialog(prompt, lines, c0,c1,c2,c3, nok)
    else if (len == 5)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4, nok)
    else if (len == 6)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5, nok)
    else if (len == 7)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5,c6, nok)
    else if (len == 8)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5,c6,c7, nok)
    else if (len == 9)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5,c6,c7,c8, nok)
    else if (len == 10)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9, nok)
    else if (len == 11)
      c = list_dialog(prompt, lines, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9,cA, nok)

    if (len > 0)
      {
      dismiss = len + 1
      res = $list_dialog_button
      }
    }
  else if (string_dlg)
    {
    if (len == 0)
      c = string_dialog(prompt, ok,nok)
    else if (len == 1)
      c = string_dialog(prompt, c0, ok,nok)
    else if (len == 2)
      c = string_dialog(prompt, c0,c1, ok,nok)
    else if (len == 3)
      c = string_dialog(prompt, c0,c1,c2, ok,nok)
    else if (len == 4)
      c = string_dialog(prompt, c0,c1,c2,c3, ok,nok)
    else if (len == 5)
      c = string_dialog(prompt, c0,c1,c2,c3,c4, ok,nok)
    else if (len == 6)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5, ok,nok)
    else if (len == 7)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5,c6, ok,nok)
    else if (len == 8)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7, ok,nok)
    else if (len == 9)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8, ok,nok)
    else if (len == 10)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9, ok,nok)
    else if (len == 11)
      c = string_dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9,cA, ok,nok)

    dismiss = len + 2
    res = $string_dialog_button
    }
  else # string_dlg false - use dialog
    {
    c = ""
    if (len == 0)
      {
      res = 0
      dismiss = 0
      }
    else if (len == 1)
      res = dialog(prompt, c0, nok)
    else if (len == 2)
      res = dialog(prompt, c0,c1, nok)
    else if (len == 3)
      res = dialog(prompt, c0,c1,c2, nok)
    else if (len == 4)
      res = dialog(prompt, c0,c1,c2,c3, nok)
    else if (len == 5)
      res = dialog(prompt, c0,c1,c2,c3,c4, nok)
    else if (len == 6)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5, nok)
    else if (len == 7)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5,c6, nok)
    else if (len == 8)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7, nok)
    else if (len == 9)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8, nok)
    else if (len == 10)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9, nok)
    else if (len == 11)
      res = dialog(prompt, c0,c1,c2,c3,c4,c5,c6,c7,c8,c9,cA, nok)

    if (len > 0)
      dismiss = len + 1
    }

    result = $empty_array
    if (len == res && more)                 # More pressed
      result["more"] = ""
    else if (res == dismiss || res == 0)    # Dismiss pressed
      result["null"] = ""
    else    # we have a string and OK (or a name button) was pressed: analyse c
      {
      if (string_dlg || use_list)
        result["line"] = c
      result["index"] = res - 1
      if ((res - 1) in buttons)
        result["button"] = buttons[res - 1]
      }

  return result
  }

# ==============================================================================
# array_ask_keys(prompt, array, [string_dlg [, lines]]): asks for an array key
#       from the ones in array, up to 5 at a time (as buttons), and/or a line.
#       If string_dlg is true, the line is the string result of a string dialog.
#       If lines is present list_dialogs will be used (even if string_dlg is
#       true) to retrieve the line value. Uses an array return value with
#       some of the following keys:
#           ["null"]    dismissed: no other values - take no further action
#           ["key"]     the string for a key - may not be present with
#                       string_dlg true and "OK" pressed
#           ["line"]    the selected line or typed text, if string_dlg or lines
#                       used - may be empty
# ==============================================================================

define array_ask_keys
  {
  prompt = $1
  array = $2
  lines = ""
  use_list = 0
  lines = ""
  string_dlg = 0
  if ($n_args == 3)
    {
    string_dlg = $3
    }
  if ($n_args >= 4)
    {
    use_list = 1
    lines = $4
    }

  buttons = $empty_array
  res = buttons
  i = 0
  n = array[]

  if (!n && string_dlg)
    {
    line = string_dialog(prompt, "OK", "Cancel")
    if ($string_dialog_button == 1)
      res["line"] = line
    else
      res["null"] = ""

    return res
    }

  lim = 10
  for (k in array)
    {
    if (length(k) > 10)
      lim = 5
    }

  for (k in array)
    {
    buttons[i++] = k                # add next key to buttons

    if (i == n)                     # no more keys in array: ask for buttons
      {
      if (use_list)
        res = arrayval_10ask(prompt, i, 0, string_dlg, buttons, lines)
      else
        res = arrayval_10ask(prompt, i, 0, string_dlg, buttons)
      }
    else if (i == lim)              # button limit reached: ask
      {
      n -= lim
      if (use_list)
        res = arrayval_10ask(prompt, i, 1, string_dlg, buttons, lines)
      else
        res = arrayval_10ask(prompt, i, 1, string_dlg, buttons)

      if ("more" in res)            # more selected: carry on
        {
        delete buttons[]
        i = 0
        delete res["more"]
        }
      else
        break                       # something selected: quit loop
      }
    }

  if ("null" in res)
    return res
  else
    {
    if ("button" in res)
      {
      res["key"] = res["button"]
      delete res["button"]
      }
    return res
    }
  }

# ==============================================================================
# array_ask_vals(prompt, array, [string_dlg [, lines]]): asks for an array value
#       from the ones in array, up to 5 at a time (as buttons), and/or a line.
#       The array must have numeric indices starting at 0.
#       If string_dlg is true, the line is the string result of a string dialog.
#       If lines is present list_dialogs will be used (even if string_dlg is
#       true) to retrieve the line value. Uses an array return value with
#       some of the following keys:
#           ["null"]    dismissed: no other values - take no further action
#           ["key"]     the string for a key - may not be present with
#                       string_dlg true and "OK" pressed
#           ["value"]   the key's value or typed in line
#           ["line"]    the selected line or typed text, if string_dlg or lines
#                       used - may be empty
# ==============================================================================

define array_ask_vals
  {
  prompt = $1
  array = $2
  lines = ""
  use_list = 0
  lines = ""
  string_dlg = 0
  if ($n_args == 3)
    {
    string_dlg = $3
    }
  if ($n_args >= 4)
    {
    use_list = 1
    lines = $4
    }

  buttons = $empty_array
  keys = buttons
  res = buttons

  i = 0
  n = array[]

  if (!n && string_dlg)
    {
    line = string_dialog(prompt, "OK", "Cancel")
    if ($string_dialog_button == 1)
      {
      res["line"] = line
      res["value"] = line
      }
    else
      res["null"] = ""

    return res
    }

  lim = 10
  for (k in array)
    {
    if (length(array[k]) > 10)
      lim = 5
    }

  for (k in array)
    {
    buttons[i] = array[k]           # add next key to buttons
    keys[i] = k

    ++i

    if (i == n)                     # no more keys in array: ask for buttons
      {
      if (use_list)
        res = arrayval_10ask(prompt, i, 0, string_dlg, buttons, lines)
      else
        res = arrayval_10ask(prompt, i, 0, string_dlg, buttons)
      }
    else if (i == lim)              # button limit reached: ask
      {
      n -= lim
      if (use_list)
        res = arrayval_10ask(prompt, i, 1, string_dlg, buttons, lines)
      else
        res = arrayval_10ask(prompt, i, 1, string_dlg, buttons)

      if ("more" in res)            # more selected: carry on
        {
        delete buttons[]
        delete keys[]
        i = 0
        delete res["more"]
        }
      else
        break                           # something selected: quit loop
      }
    }

  if ("null" in res)
    return res
  else
    {
    if ("button" in res)
      {
      res["key"] = keys[res["index"]]
      res["value"] = res["button"]
      delete res["button"]
      delete res["index"]
      }
    return res
    }
  }

# ==============================================================================
# Array entry selection - this uses a number of helper functions to format the
#       array keys and content.
# ==============================================================================

# ------------------------------------------------------------------------------
# array_select_entry_flatten_str(s [, len [, quot]]): returns s with all
#       newlines changed to '/' and tabs and space sequences changed to ' '. If
#       the result is longer than len + 3, remove everything after len and add
#       "..."). If the quot parameter is passed, its first character will be
#       added at either end of the string, not included in the length count,
#       before any added "...".
# ------------------------------------------------------------------------------

define array_select_entry_flatten_str
  {
  len = 0
  quot = ""
  if ($n_args >= 2)
    len = $2
  if ($n_args >= 3)
    quot = substring(replace_in_string($3, "\\s*", "", "regex", "copy"), 0, 1)

  s = replace_in_string($1, "\\s*\n\\s*", "/", "regex", "copy")

  s = replace_in_string(s, "\\s+", " ", "regex", "copy")

  slen = length(s)
  if (len == 0)
    len = slen

  if (slen > len + 3)
    s = quot substring(s, 0, len) quot "..."
  else if (slen > 0)
    s = quot s quot

  return s
  }

# ------------------------------------------------------------------------------
# array_select_entry_longest_key(array, null): returns the longest key that will
#       be used to format the list_dialog() lines in array_select_entry().
# ------------------------------------------------------------------------------

define array_select_entry_longest_key
  {
  array = $1
  null = $2
  if (null == "")
    null = "\"\""

  maxkey = ""
  maxlen = 0
  for (key in array)
    {
    thekey = key
    if (key == "")
      thekey = null
    else
    if (!valid_number(key))
      thekey = array_select_entry_flatten_str(key, 20, "\"")
    else
      thekey = key

    len = length(thekey)
    if (len >= maxlen)
      {
      maxlen = len
      maxkey = thekey
      }
    }
  return maxkey
  }

# ------------------------------------------------------------------------------
# array_select_entry_neg_keys_to_string(array, startline, maxkeylenstr): makes
#       lines appropriate for list_dialog() displays in array_select_entry() for
#       keys in array which are negative numbers, ordered numerically. Each line
#       has a number, starting at startline, so that a line selected in
#       list_dialog() can be identified and its key found (see ["i_to_key"]
#       below). maxkeylenstr is the longest key value as returned by
#       array_select_entry_longest_key. Returns an array with the following
#       keys:
#           ["lines"]       the string holding generated lines
#           ["next_i"]      the line number for any following line
#           ["i_to_key"]    an array of line number to key string values
# ------------------------------------------------------------------------------

define array_select_entry_neg_keys_to_string
  {
  array = $1
  startline = $2
  maxkeylenstr = $3

  ks = $empty_array
  ksi = $empty_array
  keyi = $empty_array
  lines = ""
  sep = ""
  nkeys = array[]

  for (key in array)
    {
    if (valid_number(key) && \
        search_string(key, "\\s", 0, "regex") < 0 && \
        key < 0)
      {
      skey = rjust_s(key, maxkeylenstr)
      ks[skey] = key
      }
    }
  n = ks[]
  i = 0
  for (skey in ks)
    {
    ++i
    ksi[n - i] = skey
    }
  for (i = 0; i < n; i++)
    {
    skey = ksi[i]
    key = ks[skey]
    keyi[i + startline] = key
    val = array[key]

    sval = array_select_entry_flatten_str(val, 50, "\"")    

    lines = lines sep "" rjust_s(i + startline, nkeys) ": " skey " -> " sval
    sep = "\n"
    }
  return make_array("lines", lines,          \
                    "next_i", i + startline, \
                    "i_to_key", keyi)
  }

# ------------------------------------------------------------------------------
# array_select_entry_pos_keys_to_string(array, startline, maxkeylenstr): makes
#       lines appropriate for list_dialog() displays in array_select_entry() for
#       keys in array which are non-negative numbers, ordered numerically. Each
#       line has a number, starting at startline, so that a line selected in
#       list_dialog() can be identified and its key found (see ["i_to_key"]
#       below). maxkeylenstr is the longest key value as returned by
#       array_select_entry_longest_key. Returns an array with the following
#       keys:
#           ["lines"]       the string holding generated lines
#           ["next_i"]      the line number for any following line
#           ["i_to_key"]    an array of line number to key string values
# ------------------------------------------------------------------------------

define array_select_entry_pos_keys_to_string
  {
  array = $1
  startline = $2
  maxkeylenstr = $3

  ks = $empty_array
  ksi = $empty_array
  keyi = $empty_array
  lines = ""
  sep = ""
  nkeys = array[]

  for (key in array)
    {
    if (valid_number(key) && \
        search_string(key, "\\s", 0, "regex") < 0 && \
        key >= 0)
      {
      skey = rjust_s(key, maxkeylenstr)
      ks[skey] = key
      }
    }
  n = ks[]
  i = 0
  for (skey in ks)
    {
    ksi[i] = skey
    ++i
    }
  for (i = 0; i < n; i++)
    {
    skey = ksi[i]
    key = ks[skey]
    keyi[i + startline] = key
    val = array[key]

    sval = array_select_entry_flatten_str(val, 50, "\"")    

    lines = lines sep "" rjust_s(i + startline, nkeys) ": " skey " -> " sval
    sep = "\n"
    }
  return make_array("lines", lines,          \
                    "next_i", i + startline, \
                    "i_to_key", keyi)
  }

# ------------------------------------------------------------------------------
# array_select_entry_nul_key_to_string(array, startline, maxkeylenstr, null):
#       makes a single line appropriate for list_dialog() displays in
#       array_select_entry() for the empty string key in array. The line has a
#       number, startline, so that if selected in list_dialog(), it can be
#       identified and its key found (see ["i_to_key"] below). maxkeylenstr is
#       the longest key value as returned by array_select_entry_longest_key.
#       Returns an array with the following keys:
#           ["lines"]       the string holding the generated line
#           ["next_i"]      the line number for any following line
#           ["i_to_key"]    an array of line number to key string values
# ------------------------------------------------------------------------------

define array_select_entry_nul_key_to_string
  {
  array = $1
  startline = $2
  maxkeylenstr = $3
  null = $4

  keyi = $empty_array
  lines = ""
  nkeys = array[]

  i = 0
  if ("" in array)
    {
    keyi[i + startline] = ""
    i = 1
    val = array[""]

    sval = array_select_entry_flatten_str(val, 50, "\"")    

    lines = rjust_s(startline, nkeys) \
            ": " ljust_s(null, maxkeylenstr) " -> " sval
    }
  return make_array("lines", lines,          \
                    "next_i", i + startline, \
                    "i_to_key", keyi)
  }

# ------------------------------------------------------------------------------
# array_select_entry_str_keys_to_string(array, startline, maxkeylenstr): makes
#       lines appropriate for list_dialog() displays in array_select_entry() for
#       keys in array which are non-nnumeric strings, ordered as in the array.
#       Each line has a number, starting at startline, so that a line selected
#       in list_dialog() can be identified and its key found (see ["i_to_key"]
#       below). maxkeylenstr is the longest key value as returned by
#       array_select_entry_longest_key. Returns an array with the following
#       keys:
#           ["lines"]       the string holding generated lines
#           ["next_i"]      the line number for any following line
#           ["i_to_key"]    an array of line number to key string values
# ------------------------------------------------------------------------------

define array_select_entry_str_keys_to_string
  {
  array = $1
  startline = $2
  maxkeylenstr = $3

  keyi = $empty_array
  lines = ""
  sep = ""
  nkeys = array[]
  i = 0

  for (key in array)
    {
    if (valid_number(key) && search_string(key, "\\s", 0, "regex") < 0)
      continue
    else if (key == "")
      continue

    keyi[i + startline] = key
    val = array[key]

    skey = array_select_entry_flatten_str(key, 20, "\"")

    if (valid_number(val))
      sval = val
    else if (val == "")
      sval = "<empty string>"
    else
      sval = array_select_entry_flatten_str(val, 50, "\"")

    lines = lines sep rjust_s(i + startline, nkeys) ": " \
                      ljust_s(skey, maxkeylenstr) " -> " sval
    sep = "\n"
    i++
    }

  return make_array("lines", lines,          \
                    "next_i", i + startline, \
                    "i_to_key", keyi)
  }

# ==============================================================================
# array_select_entry(prompt, array [, button1, ... button7]): uses a
#       list_dialog() to ask the user to select an array entry (which must
#       contain only scalar values). Returns an array with the indices
#           ["key"]     the string for a key - may not be present with
#                       string_dlg true and "OK" pressed
#           ["value"]   the key's value or typed in line
#           ["btnnum"]  the button number
#           ["button"]  the button text
#       The returned array is empty if no button was pressed. ["key"] and
#       ["value"] may not be present if no entry was selected. If no button was
#       given, only ["key"] and ["value"] may be returned.
# ==============================================================================

define array_select_entry
  {
  # pick up arguments
  if ($n_args > 9)
    array_select_entry_TooManyButtons() # cause failure
  prompt = $1
  array = $2
  b = $empty_array
  nbtns = $n_args - 2
  for (i = 1; i <= nbtns; i++)
    b[i] = $args[i + 2]

  # set up result array
  res = $empty_array

  # build up list_dialog()'s list
  null_k = "<empty key>"
  keyi = $empty_array
  nline = 0
  nkeys = array[]
  if (nkeys == 0)
    lines = "<empty array>"
  else
    {
    null_key = "<empty key>"
    long_key = array_select_entry_longest_key(array, null_k)

    nline = 1
    key_title = ljust_s("<Key>", long_key)
    lines = rjust_s("", nkeys) "  " key_title " -> <Value>"

    step = array_select_entry_nul_key_to_string(array, nline, long_key, null_k)
    keyi = keyi + step["i_to_key"]
    nline = step["next_i"]
    lines = lines "\n" step["lines"]

    step = array_select_entry_neg_keys_to_string(array, nline, long_key)
    keyi = keyi + step["i_to_key"]
    nline = step["next_i"]
    lines = lines "\n" step["lines"]

    step = array_select_entry_pos_keys_to_string(array, nline, long_key)
    keyi = keyi + step["i_to_key"]
    nline = step["next_i"]
    lines = lines "\n" step["lines"]

    step = array_select_entry_str_keys_to_string(array, nline, long_key)
    keyi = keyi + step["i_to_key"]
    nline = step["next_i"]
    lines = lines "\n" step["lines"]
    }

  # now call up the dialog
  if (nbtns == 0)
    s = list_dialog(prompt, lines)
  else if (nbtns == 1)
    s = list_dialog(prompt, lines, b[1])
  else if (nbtns == 2)
    s = list_dialog(prompt, lines, b[1], b[2])
  else if (nbtns == 3)
    s = list_dialog(prompt, lines, b[1], b[2], b[3])
  else if (nbtns == 4)
    s = list_dialog(prompt, lines, b[1], b[2], b[3], b[4])
  else if (nbtns == 5)
    s = list_dialog(prompt, lines, b[1], b[2], b[3], b[4], b[5])
  else if (nbtns == 6)
    s = list_dialog(prompt, lines, b[1], b[2], b[3], b[4], b[5], b[6])
  else # if (nbtns == 7) # already checked
    s = list_dialog(prompt, lines, b[1], b[2], b[3], b[4], b[5], b[6], b[7])

  btn = $list_dialog_button

  # get the key number from the returned string s
  i = 0
  if (nline > 0)
    i = to_number(s)
  if (i in keyi)
    {
    key = keyi[i]
    res["key"] = key
    res["value"] = array[key]
    }
  if (btn != 0 && btn <= nbtns)
    {
    res["btnnum"] = btn
    res["button"] = b[btn]
    }

  return res
  }