prologue.ast

------------------------------------------------------------------
-- prologue.ast
--
-- the standard Asteroid prologue defining global functions.
--
-- (c) University of Rhode Island
------------------------------------------------------------------
-- Note: this is just a file with definitions that need to wind 
-- up in the global scope of the interpreter.


------------------------------------------------------------------
structure Error
------------------------------------------------------------------
-- convenient user level exceptions
with
  data err_val.
  function __init__
    with val do
      let this @err_val = val.
    end
  end

------------------------------------------------------------------
structure Exception
------------------------------------------------------------------
-- asteroid's standard exception structure.
-- note: both the kind and the val fields have to be given
with
  data kind.
  data val.
  function __init__
    with (kind:%string,val) do
      let this @kind = kind.
      let this @val = val.
    end
  end

------------------------------------------------------------------
function len
------------------------------------------------------------------
with item do return escape
"
global __retval__
from asteroid.support import data_only

item_val = state.symbol_table.lookup_sym('item')

if item_val[0] in ['list','tuple','string']:
    __retval__ = ('integer', len(item_val[1]))
elif item_val[0] == 'object':
    (OBJECT,
        (STRUCT_ID, (ID, name)),
        (MEMBER_NAMES, (LIST, member_names)),
        (OBJECT_MEMORY, (LIST, object_memory))) = item_val
    l = len(data_only(object_memory))
    __retval__ = ('integer', l)
elif item_val[0] == 'struct':
    (STRUCT,
        (MEMBER_NAMES, (LIST, member_names)),
        (STRUCT_MEMORY, (LIST, struct_memory))) = item_val
    l = len(data_only(struct_memory))
    __retval__ = ('integer', l)

else:
    raise ValueError(
   	  'len expected a list, tuple, string, or structure got \'{}\''
	    .format(item_val[0]))
"
end

------------------------------------------------------------------
function hd
------------------------------------------------------------------
-- return the first element of a list, error is list is empty
with [] do
  throw Exception("ValueError","empty list not supported").
with l:%list do
  return l@0.
end

------------------------------------------------------------------
function tl
------------------------------------------------------------------
-- return the rest of the list without the first element
with [] do
throw Exception("ValueError","empty list not supported").
with [_] do
  return [].
with l:%list do
  return l@[1 to len(l)-1].
end

------------------------------------------------------------------
function range
------------------------------------------------------------------
  with (start:%integer,stop:%integer) do
    return [start to stop-1].
  with (start:%integer,stop:%integer,inc:%integer) do
    return [start to stop-1 step inc].
  with stop:%integer do
    return [0 to stop-1].
  end

------------------------------------------------------------------
function getid
------------------------------------------------------------------
-- get the id (physical memory address) of 'x' as an Asteroid integer
with x do return escape
"
global __retval__
x_val = state.symbol_table.lookup_sym('x')
__retval__ = ('integer', id(x_val))
"
end

------------------------------------------------------------------
function isdefined
------------------------------------------------------------------
-- return true if a variable or type name is defined in the
-- current environment otherwise return false
-- the variable and type name is given as a string
with __x__:%string do return escape
"
global __retval__
(STRING, v)  = state.symbol_table.lookup_sym('__x__')
try:
   state.symbol_table.lookup_sym(v)
except ValueError:
    __retval__ = ('boolean', False)
else:
   __retval__ = ('boolean', True)
 "
end

------------------------------------------------------------------
structure loc
------------------------------------------------------------------
-- object to identify locations for index member functions.
-- applies to both lists and strings.
with
   data startix.
   data endix.
   function __init__
      with (startval:%integer,endval:%integer) do
         let this @startix = startval.
         let this @endix = endval.
      with startval:%integer do
         let this @startix = startval.
         let this @endix = none.
      end
end

------------------------------------------------------------------
let __TP__ = pattern
------------------------------------------------------------------
-- pattern for selecting proper formatting body in 'tostring'
with x if (x is %boolean) or
         (x is %integer) or
         (x is %string).

------------------------------------------------------------------
structure __STRINGFORMAT__
------------------------------------------------------------------
-- formatting object for 'tostring'
with
  data length.
  data precision.
  data scientific.
  function __init__
    with (l:%integer,p:%integer,s:%boolean) do
      let this @length = l.
      let this @precision = p.
      let this @scientific = s.
    with (l:%integer,p:%integer) do
      let this @length = l.
      let this @precision = p.
      let this @scientific = none.
    with l:%integer do
      let this @length = l.
      let this @precision = none.
      let this @scientific = none.
    end
end

------------------------------------------------------------------
-- TYPE CONVERSION FUNCTIONS --
------------------------------------------------------------------

------------------------------------------------------------------
function tobase
------------------------------------------------------------------
-- represent the given integer x as a numeral in different bases
with (x:%integer,base:%integer) do return escape
"
global __retval__

x_val = state.symbol_table.lookup_sym('x')
base_val = state.symbol_table.lookup_sym('base')

if base_val[1] == 2:
  __retval__ = ('string', format(x_val[1],'b'))
elif base_val[1] == 8:
  __retval__ = ('string', format(x_val[1],'o'))
elif base_val[1] == 16:
  __retval__ = ('string', format(x_val[1],'X'))
else:
  raise ValueError('illegal base value {}'
          .format(base_val[1]))
"
end

-- Note: we no longer support this, it encourages lazy programming
-- by relying on the fuzzy concept of "truthiness"
------------------------------------------------------------------
-- function toboolean
------------------------------------------------------------------
-- with item do return escape
-- "
-- global __retval__
--
-- item_val = state.symbol_table.lookup_sym('item')
-- __retval__ = map2boolean(item_val)
-- "
-- end

------------------------------------------------------------------
function tointeger
------------------------------------------------------------------
with (item:%string,base:%integer) do return escape
"
global __retval__
item_val = state.symbol_table.lookup_sym('item')
base_val = state.symbol_table.lookup_sym('base')
__retval__ = ('integer', int(item_val[1], base=base_val[1]))
"
with item do return escape
"
global __retval__

item_val = state.symbol_table.lookup_sym('item')
__retval__ = ('integer', int(item_val[1]))
"
end

------------------------------------------------------------------
function toreal
------------------------------------------------------------------
with item do return escape
"
global __retval__

item_val = state.symbol_table.lookup_sym('item')
__retval__ = ('real', float(item_val[1]))
"
end

------------------------------------------------------------------
function tostring
------------------------------------------------------------------
-- convert an asteroid object to string.
-- if format values are given apply the
-- formatting to the object.

with (v:*__TP__,__STRINGFORMAT__(w:%integer,none,none)) do
  -- booleans, integers, and strings (see TP pattern) with width spec are
  -- right justified. if width spec is too narrow it is ignored.
  let vs = tostring v.
  let padl = w - vs @length().
  if padl > 0 do
    return [1 to padl] @map(lambda with _ do return " ") @join("") + vs.
  else do
    return vs.
  end
with (v:%real,__STRINGFORMAT__(w:%integer,none,none)) do return escape
-- floating point values with only a width spec are left justified with
-- zero padding on the right.
"
global __retval__
(V_TYPE, v_val) = state.symbol_table.lookup_sym('v')
(W_TYPE, w_val) = state.symbol_table.lookup_sym('w')

fmtstr = '{:'+str(w_val)+'f}'
__retval__ = ('string', fmtstr.format(v_val))
"
-- floating point values with a width and precision specs
-- are formatted according to Python formatting rules
with (v:%real,__STRINGFORMAT__(w:%integer,p:%integer,none)) do return escape
"
global __retval__
(V_TYPE, v_val) = state.symbol_table.lookup_sym('v')
(W_TYPE, w_val) = state.symbol_table.lookup_sym('w')
(P_TYPE, p_val) = state.symbol_table.lookup_sym('p')

fmtstr = '{:'+str(w_val)+'.'+str(p_val)+'f}'
__retval__ = ('string', fmtstr.format(v_val))
"
-- floating point values with width, precision and scientific notation specs
-- are formatted according to Python formatting rules
with (v:%real,__STRINGFORMAT__(w:%integer,p:%integer,s:%boolean)) do return escape
"
global __retval__
(V_TYPE, v_val) = state.symbol_table.lookup_sym('v')
(W_TYPE, w_val) = state.symbol_table.lookup_sym('w')
(P_TYPE, p_val) = state.symbol_table.lookup_sym('p')
(S_TYPE, s_val) = state.symbol_table.lookup_sym('s')

fmtstr = '{:'+str(w_val)+'.'+str(p_val)+('e}' if s_val else 'f}')
__retval__ = ('string', fmtstr.format(v_val))
"
with item do return escape
-- default clause
"
global __retval__
from asteroid.support import term2string

item_val = state.symbol_table.lookup_sym('item')
__retval__ = ('string', term2string(item_val))
"
end

------------------------------------------------------------------
function stringformat
------------------------------------------------------------------
-- a wrapper around our __STRINGFORMAT__ object as a member
-- of our module.
with (l:%integer,p:%integer,s:%boolean) do
  return __STRINGFORMAT__(l,p,s).
with (l:%integer,p:%integer) do
  return __STRINGFORMAT__(l,p).
with l:%integer do
  return __STRINGFORMAT__(l).
end

------------------------------------------------------------------
-- TYPE QUERY FUNCTIONS --
------------------------------------------------------------------

------------------------------------------------------------------
function islist
------------------------------------------------------------------
with item do
  return item is %list
end

------------------------------------------------------------------
function isnone
------------------------------------------------------------------
with x do
  return x is %none.
end

------------------------------------------------------------------
function isscalar
------------------------------------------------------------------
with item do
  return (item is %integer) or (item is %real).
end

------------------------------------------------------------------
function gettype
------------------------------------------------------------------
-- get the type of 'x' as an Asteroid string
with x do return escape
"
global __retval__
val = state.symbol_table.lookup_sym('x')
if val[0] == 'object':
  (OBJECT, (STRUCT_ID, (ID, x_type)), MEMBER_LIST, OBJECT_MEMORY) = val
elif val[0] in ['function-val','member-function-val']:
  # internally we store functions as function values
  # but to the user these look like functions as the 
  # type counter part to the %function type pattern
  # will match both function-val and member-function-val
  x_type = 'function'
else:
  x_type = val[0]
__retval__ = ('string', x_type)
"
end

------------------------------------------------------------------
-- List member functions
------------------------------------------------------------------

-- NOTE: these functions must appear the
-- 'list_member_functions' dictionary

-- for implementation details see python lists in
-- https://docs.python.org/3/tutorial/datastructures.html

-- list member function association table
escape
"
global list_member_functions

list_member_functions.update({
    'length'    : '__list_length__',
    'append'    : '__list_append__',
    'extend'    : '__list_extend__',
    'insert'    : '__list_insert__',
    'remove'    : '__list_remove__',
    'pop'       : '__list_pop__',
    'clear'     : '__list_clear__',
    'index'     : '__list_index__',
    'count'     : '__list_count__',
    'sort'      : '__list_sort__',
    'reverse'   : '__list_reverse__',
    'copy'      : '__list_copy__',
    'shuffle'   : '__list_shuffle__',
    'map'       : '__list_map__',
    'reduce'    : '__list_reduce__',
    'filter'    : '__list_filter__',
    'member'    : '__list_member__',
    'join'      : '__list_join__',
    })
".
------------------------------------------------------------------
function __list_length__
------------------------------------------------------------------
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('integer', len(this_val[1]))
"
end

------------------------------------------------------------------
function __list_append__
------------------------------------------------------------------
-- Add an item to the end of the list.
with item do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

this_val[1].append(item_val)
__retval__ = this_val
"
end

------------------------------------------------------------------
function __list_extend__
------------------------------------------------------------------
-- Extend the list by appending all the items
-- from the item where item is either a list or a tuple.
with item do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

if item_val[0] not in ['list', 'tuple']:
    raise ValueError('extend expected a list, string, or tuple, got \'{}\''
                .format(item_val[0]))

__retval__ = ('list', this_val[1].extend(item_val[1]))
"
end

------------------------------------------------------------------
function __list_insert__
------------------------------------------------------------------
-- Insert an item at a given position. The first
-- argument is the index of the element before
-- which to insert, so a@insert(0, x) inserts at the
-- front of the list, and a@insert(a@length(), x) is
-- equivalent to a@append(x).
with (ix:%integer,item) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
ix_val = state.symbol_table.lookup_sym('ix')
item_val = state.symbol_table.lookup_sym('item')

__retval__ = ('list', this_val[1].insert(ix_val[1],item_val))
"
end

------------------------------------------------------------------
function __list_remove__
------------------------------------------------------------------
-- Remove the first element from the list whose
-- value is equal to item. It raises a ValueError
-- if there is no such item.
with item do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

__retval__ = ('list', this_val[1].remove(item_val))
"
end

------------------------------------------------------------------
function __list_pop__
------------------------------------------------------------------
-- Remove the item at the given position in
-- the list, and return it. If no index is specified,
-- a@pop() removes and returns the last item in the list.
with ix:%integer do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
ix_val = state.symbol_table.lookup_sym('ix')

__retval__ = this_val[1].pop(ix_val[1])
"
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = this_val[1].pop()
"
end

------------------------------------------------------------------
function __list_clear__
------------------------------------------------------------------
-- Remove all items from the list.
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('list', this_val[1].clear())
"
end

------------------------------------------------------------------
function __list_index__
------------------------------------------------------------------
-- Return zero-based index in the list of the first element whose value
-- is equal to item. Raises a ValueError exception if there is no such item.
-- The optional arguments startix and endix are interpreted as in the slice
-- notation and are used to limit the search to a particular subsequence of
-- the list. The returned index is computed relative to the beginning of the
-- full sequence rather than the startix argument.
with (item,loc(startix:%integer,endix:%integer)) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')
startix_val = state.symbol_table.lookup_sym('startix')
endix_val = state.symbol_table.lookup_sym('endix')

__retval__ = ('integer', this_val[1].index(item_val,
                            startix_val[1],
                            endix_val[1]))
"
with (item,loc(startix:%integer,none)) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')
startix_val = state.symbol_table.lookup_sym('startix')

__retval__ = ('integer', this_val[1].index(item_val, startix_val[1]))
"
with item do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

__retval__ = ('integer', this_val[1].index(item_val))
"
end

------------------------------------------------------------------
function __list_count__
------------------------------------------------------------------
-- Return the number of times item appears in the list.
with item do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

__retval__ = ('integer', this_val[1].count(item_val))
"
end

------------------------------------------------------------------
function __list_sort__
------------------------------------------------------------------
-- Sort the items of the list in place
with (reverse:%boolean) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
reverse_val = state.symbol_table.lookup_sym('reverse')

this_val[1].sort(reverse=reverse_val[1])
__retval__ = this_val
"
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
this_val[1].sort()
__retval__ = this_val
"
end

------------------------------------------------------------------
function __list_reverse__
------------------------------------------------------------------
-- Reverse the elements of the list in place.
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
this_val[1].reverse()
__retval__ = this_val
"
end

------------------------------------------------------------------
function __list_copy__
------------------------------------------------------------------
-- make a shallow copy of the list
with none do
  let new_list = [].
  for e in this do
    let new_list = new_list + [e].
  end
  return new_list.
end

------------------------------------------------------------------
function __list_shuffle__
------------------------------------------------------------------
-- return a random permutation of a given list - in place!
with none do return escape
"
global __retval__
import random

this_val = state.symbol_table.lookup_sym('this')
random.shuffle(this_val[1])
__retval__ = this_val
"
end

------------------------------------------------------------------
function __list_map__
------------------------------------------------------------------
-- Apply f to each element of the list
with f:%function do
    let r = [].
    for i in this do
        r @append(f i).
    end
    return r.
end

------------------------------------------------------------------
function __list_reduce__
------------------------------------------------------------------
-- Note: first arg to f is the accumulator
with f:%function do
    let value = this@0.
    for i in 1 to this@length()-1 do
        let value = f(value,this@i).
    end
    return value.
with (f:%function,init) do
    let value = init.
    for i in 0 to this@length()-1 do
        let value = f(value,this@i).
    end
    return value.
end

------------------------------------------------------------------
function __list_filter__
------------------------------------------------------------------
-- Construct an output list from those elements of the list for which
-- f returns true. If f is none, the identity function is assumed,
-- that is, all elements of input list that are false are removed.
with f:%function do
    let out = [].
    for e in this do
        let r = f e.
        if gettype r =/= "boolean" do 
          escape "raise ValueError('list filter function has to return a Boolean')"
        end
        let out = out+([e] if r else []).
    end
    return out.
end

------------------------------------------------------------------
function __list_member__
------------------------------------------------------------------
with item do
    if this @count(item) > 0 do
        return true.
    else do
        return false.
    end
end

------------------------------------------------------------------
function __list_join__
------------------------------------------------------------------
with join:%string do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
join_val = state.symbol_table.lookup_sym('join')

# convert Asteroid list into a Python list
raw_list = []
for (t,v) in this_val[1]:
  if t != 'string':
    raise ValueError('join: string list only')
  raw_list.append(v)

__retval__ = ('string', join_val[1].join(raw_list))
"
end


------------------------------------------------------------------
-- String member functions
------------------------------------------------------------------

-- NOTE: these functions must appear the
-- 'string_member_functions' dictionary

-- for implementation details see python lists in
-- https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str
escape
"
global string_member_functions

string_member_functions.update({
    'length'    : '__string_length__',
    'explode'   : '__string_explode__',
    'trim'      : '__string_trim__',
    'replace'   : '__string_replace__',
    'split'     : '__string_split__',
    'toupper'   : '__string_toupper__',
    'tolower'   : '__string_tolower__',
    'index'     : '__string_index__',
    'flip'      : '__string_flip__',
    })
    "

------------------------------------------------------------------
function __string_length__
------------------------------------------------------------------
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('integer', len(this_val[1]))
"
end

------------------------------------------------------------------
function __string_explode__
------------------------------------------------------------------
with none do
  let l = [].
  for c in this do
      let l = l+[c].
  end
  return l.
end

------------------------------------------------------------------
function __string_trim__
------------------------------------------------------------------
-- Return a copy of the string with the leading and trailing
-- characters removed. The what argument is a string specifying
-- the set of characters to be removed. If omitted or none, the what
-- argument defaults to removing whitespace. The what argument is
-- not a prefix or suffix; rather, all combinations of its values are stripped.
with what:%string do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
what_val = state.symbol_table.lookup_sym('what')
__retval__ = ('string', this_val[1].strip(what_val[1]))
"
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('string', this_val[1].strip())
"
end

------------------------------------------------------------------
function __string_replace__
------------------------------------------------------------------
-- Return a copy of the string with all occurrences of regular expression pattern
-- old replaced by the string new. If the optional argument count is given,
-- only the first count occurrences are replaced.
with (old:%string,new:%string,count:%integer) do return escape
"
global __retval__
from re import sub

this_val = state.symbol_table.lookup_sym('this')
old_val = state.symbol_table.lookup_sym('old')
new_val = state.symbol_table.lookup_sym('new')
count_val = state.symbol_table.lookup_sym('count')

__retval__ = ('string', sub(old_val[1], new_val[1], this_val[1], count_val[1]))
"
with (old:%string,new:%string) do return escape
"
global __retval__
from re import sub

this_val = state.symbol_table.lookup_sym('this')
old_val = state.symbol_table.lookup_sym('old')
new_val = state.symbol_table.lookup_sym('new')

__retval__ = ('string', sub(old_val[1], new_val[1],this_val[1]))
"
end

------------------------------------------------------------------
function __string_split__
------------------------------------------------------------------
-- Return a list of the words in the string, using sep as the delimiter string.
-- If maxsplit is given, at most maxsplit splits are done (thus, the list will
-- have at most maxsplit+1 elements). If maxsplit is not specified or -1, then
-- there is no limit on the number of splits (all possible splits are made).
--
--  sep is given, consecutive delimiters are not grouped together and are
-- deemed to delimit empty strings (for example, '1,,2'.split(',') returns ['1', '', '2']).
-- The sep argument may consist of multiple characters (for example,
-- '1<>2<>3'.split('<>') returns ['1', '2', '3']). Splitting an empty string with a
-- specified separator returns [''].
--
-- If sep is not specified or is None, a different splitting algorithm is applied: runs of
-- consecutive whitespace are regarded as a single separator, and the result will
-- contain no empty strings at the start or end if the string has leading or trailing
-- whitespace. Consequently, splitting an empty string or a string consisting of
-- just whitespace with a None separator returns [].
with (sep:%string,count:%integer) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
sep_val = state.symbol_table.lookup_sym('sep')
count_val = state.symbol_table.lookup_sym('count')

raw_list = this_val[1].split(sep_val[1], count_val[1])
ast_list = [('string',e) for e in raw_list]

__retval__ = ('list', ast_list)
"
with sep:%string do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
sep_val = state.symbol_table.lookup_sym('sep')

raw_list = this_val[1].split(sep_val[1])
ast_list = [('string',e) for e in raw_list]

__retval__ = ('list', ast_list)
"
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')

raw_list = this_val[1].split()
ast_list = [('string',e) for e in raw_list]

__retval__ = ('list', ast_list)
"
end

------------------------------------------------------------------
function __string_toupper__
------------------------------------------------------------------
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('string', this_val[1].upper())
"
end

------------------------------------------------------------------
function __string_tolower__
------------------------------------------------------------------
with none do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
__retval__ = ('string', this_val[1].lower())
"
end

------------------------------------------------------------------
function __string_index__
------------------------------------------------------------------
with (item:%string,loc(startix:%integer,endix:%integer)) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')
startix_val = state.symbol_table.lookup_sym('startix')
endix_val = state.symbol_table.lookup_sym('endix')

val = this_val[1].find(item_val[1], startix_val[1], endix_val[1])
__retval__ = ('integer', val)
"
with (item:%string,loc(startix:%integer,none)) do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')
startix_val = state.symbol_table.lookup_sym('startix')

val = this_val[1].find(item_val[1], startix_val[1])
__retval__ = ('integer',val)
"
with item:%string do return escape
"
global __retval__

this_val = state.symbol_table.lookup_sym('this')
item_val = state.symbol_table.lookup_sym('item')

val = this_val[1].find(item_val[1])
__retval__ = ('integer',val)
"
end

------------------------------------------------------------------
function __string_flip__
------------------------------------------------------------------
with none do
    return this @explode()
                @reverse()
                @join("").
end