/*

 *   Copyright 2000, 2006 Michael J. Roberts.

 *   

 *   This file is part of TADS 3.

 *   

 *   This module defines the fundamental intrinsic classes, including Object,

 *   String, Collection, List, and Iterator.  

 */

#ifndef _SYSTYPE_H_

#define _SYSTYPE_H_

/* ------------------------------------------------------------------------ */

/*

 *   TADS datatype codes.  These values are returned by propType(), etc.  

 */

#define TypeNil         1

#define TypeTrue        2

#define TypeObject      5

#define TypeProp        6

#define TypeInt         7

#define TypeSString     8

#define TypeDString     9

#define TypeList        10

#define TypeCode        11

#define TypeFuncPtr     12

#define TypeNativeCode  14

#define TypeEnum        15

/* ------------------------------------------------------------------------ */

/*

 *   The root object class.  All objects descend from this class. 

 */

intrinsic class Object 'root-object/030004'

{

    /* 

     *   Determine if I'm an instance or subclass of the given class 'cls'.

     *   Note that x.ofKind(x) returns true - an object is of its own kind.  

     */

    ofKind(cls);

    /* get the list of direct superclasses of this object */

    getSuperclassList();

    /* determine if a property is defined or inherited by this object */

    propDefined(prop, flags?);

    /* get the type of a property defined for this object */

    propType(prop);

    /* 

     *   Get a list of my directly-defined properties.  When called on

     *   intrinsic class objects, this returns a list of properties defined

     *   for instances of the class, as well as static properties of the

     *   class.  

     */

    getPropList();

    /* 

     *   get parameter list information for the given method - returns a

     *   list: [minimumArgc, optionalArgc, varargs], where minimumArgc is

     *   the minimum number of arguments, optionalArgc is the number of

     *   additional optional arguments, and varargs is true if the function

     *   takes a varying number of arguments greater than or equal to the

     *   minimum, nil if not.  

     */

    getPropParams(prop);

    /* 

     *   determine if I'm a "class" object - returns true if the object was

     *   defined with the "class" keyword, nil otherwise 

     */

    isClass();

    /* 

     *   Determine if a property is inherited further from the given object.

     *   definingObj is usually the value of the 'definingobj'

     *   pseudo-variable, and origTargetObj is usually the value of the

     *   'targetobj' pseudo-variable.  

     */

    propInherited(prop, origTargetObj, definingObj, flags?);

    /* determine if this instance is transient */

    isTransient();

}

/*

 *   propDefined() flags 

 */

#define PropDefAny           1

#define PropDefDirectly      2

#define PropDefInherits      3

#define PropDefGetClass      4

/* ------------------------------------------------------------------------ */

/*

 *   The IntrinsicClass intrinsic class.  Objects of this type represent the

 *   intrinsic classes themselves.  

 */

intrinsic class IntrinsicClass 'intrinsic-class/030000': Object

{

}

/*

 *   Intrinsic class modifier object (for internal compiler use only) 

 */

intrinsic class IntrinsicClassModifier 'int-class-mod/030000'

{

}

/* ------------------------------------------------------------------------ */

/*

 *   The native collection type - this is the base class for lists, vectors,

 *   and other objects that represent collections of values.  

 */

intrinsic class Collection 'collection/030000': Object

{

    /* 

     *   Create an iterator for the collection.  This returns a new Iterator

     *   object that can be used to iterate over the values in the

     *   collection.  The Iterator will use a snapshot of the collection that

     *   will never change, even if the collection is changed after the

     *   iterator is created.  

     */

    createIterator();

    /*

     *   Create a "live iterator" for the collection.  This returns a new

     *   Iterator object that refers directly to the original collection; if

     *   the original collection changes, the iterator will reflect the

     *   changes in its iteration.  As a result, the iterator is not

     *   guaranteed to visit all of the elements in the collection if the

     *   collection changes during the course of the iteration.  If

     *   consistent results are required, use createIterator() instead.  

     */

    createLiveIterator();

}

/* ------------------------------------------------------------------------ */

/*

 *   The native iterator type - this is the base class for all iterators.

 *   This class is abstract and is thus never directly instantiated.

 *   

 *   Note that iterators can never be created directly with the 'new'

 *   operator.  Instead, iterators must be obtained from a collection via the

 *   collection's createIterator() method.  

 */

intrinsic class Iterator 'iterator/030001': Object

{

    /*

     *   Get the next item in the collection.  This returns the next item's

     *   value, and advances the internal state in the iterator so that a

     *   subsequent call to getNext() returns the next item after this one.

     *   When the iterator is first created, or after calling

     *   resetIterator(), this returns the first item in the collection.  

     */

    getNext();

    /*

     *   Determine if the collection is out of items.  Returns true if

     *   getNext() will return a valid item, nil if no more items are

     *   available.  

     */

    isNextAvailable();

    /*

     *   Reset to the first item.  After calling this routine, the next call

     *   to getNext() will return the first item in the collection.  

     */

    resetIterator();

    /*

     *   Get the current key.  This returns the value of the key for the

     *   current item in the collection.  For an indexed collection, this

     *   returns the index value; for a keyed collection, this returns the

     *   current key value.  

     */

    getCurKey();

    /*

     *   Get the current value.  This returns the value of the current item

     *   in the collection. 

     */

    getCurVal();

}

/*

 *   Indexed object iterator - this type of iterator is used for lists,

 *   vectors, and other indexed collection objects.  

 */

intrinsic class IndexedIterator 'indexed-iterator/030000': Iterator

{

}

/* ------------------------------------------------------------------------ */

/*

 *   AnonFuncPtr depends on Vector 

 */

#include "vector.h"

/*

 *   Anonymous function pointer intrinsic class 

 */

intrinsic class AnonFuncPtr 'anon-func-ptr': Vector

{

}

/* ------------------------------------------------------------------------ */

/*

 *   The "TADS Object" intrinsic class.  All objects that the program

 *   defines with the "class" or "object" statements descend from this

 *   class.  

 */

intrinsic class TadsObject 'tads-object/030004': Object

{

    /* 

     *   Create an instance of this object: in other words, create a new

     *   object whose superclass is this object.  The arguments provided are

     *   passed to the new object's constructor.  This method returns a

     *   reference to the new object.  

     */

    createInstance(...);

    /*

     *   Create a clone of this object.  This creates an exact copy, with

     *   the same property values, as the original.  This does not call any

     *   constructors; it merely instantiates an exact copy of the original.

     *   

     *   Note that the clone is a "shallow" copy, which means that any

     *   objects it references are not themselves cloned.

     */

    createClone();

    /*

     *   Create a transient instance of this object.  This works just like

     *   createInstance(), but creates a transient instance instead of an

     *   ordinary (persistent) instance.  

     */

    createTransientInstance(...);

    /*

     *   Create an instance of an object based on multiple superclasses.

     *   Each argument gives a superclass, and optionally arguments for

     *   invoking the superclass constructor.  If an argument is given as

     *   simply a class, then we don't invoke that superclass's constructor;

     *   if the argument is given as a list, the first element of the list is

     *   the class, and the remaining elements of the list are arguments for

     *   that superclass's constructor.  The arguments are specified in the

     *   same order they would be to define the object, so the first argument

     *   is the dominant superclass.

     *   

     *   For example, suppose we created a class definition like this:

     *   

     *   class D: A, B, C

     *.    construct(x, y)

     *.    {

     *.      inherited A(x);

     *.      inherited C(y);

     *.    }

     *.  ;

     *   

     *   We could obtain the same effect dynamically like so:

     *   

     *   local d = TadsObject.createInstanceOf([A, x], B, [C, y]); 

     */

    static createInstanceOf(...);

    /*

     *   Create a transient instance based on multiple superclasses.  This

     *   works just like createInstanceOf(), but creates a transient

     *   instance. 

     */

    static createTransientInstanceOf(...);

    /*

     *   Set the superclass list.  scList is a list giving the new

     *   superclasses.  The superclasses must all be TadsObject objects, with

     *   one exception: the list [TadsObject] may be passed to create an

     *   object based directly on TadsObject.  No other intrinsic classes can

     *   be used in the list, and objects of other types cannot be used in

     *   the list.  

     */

    setSuperclassList(scList);

}

/* ------------------------------------------------------------------------ */

/* 

 *   We need CharacterSet and ByteArray (for String.mapToByteArray).  (But

 *   wait to include these until after we've defined Object, since everything

 *   depends on Object.)  

 */

#include "charset.h"

#include "bytearr.h"

/* ------------------------------------------------------------------------ */

/*

 *   The native string type. 

 */

intrinsic class String 'string/030005': Object

{

    /* get the length of the string */

    length();

    /* extract a substring */

    substr(start, len?);

    /* convert to upper case */

    toUpper();

    /* convert to lower case */

    toLower();

    /* find a substring */

    find(str, index?);

    /* 

     *   convert to a list of Unicode character codes, or get the Unicode

     *   character code for the single character at the given index 

     */

    toUnicode(idx?);

    /* htmlify a string */

    htmlify(flags?);

    /* determine if we start with the given string */

    startsWith(str);

    /* determine if we end with the given string */

    endsWith(str);

    /* 

     *   Map to a byte array, converting to the given character set.

     *   'charset' must be an object of intrinsic class CharacterSet; the

     *   characters in the string will be mapped from the internal Unicode

     *   representation to the appropriate byte representation in the given

     *   character set.  

     */

    mapToByteArray(charset);

    /* 

     *   Replace one occurrence or all occurrences of the given substring

     *   with the given new string.  

     */

    findReplace(origStr, newStr, flags, index?);

}

/*

 *   Flags for String.htmlify 

 */

/* 

 *   translate spaces - each space in a run of multiple spaces is converted

 *   to an   sequence 

 */

#define HtmlifyTranslateSpaces    0x0001

/* translate newlines - converts each \n character to a <br> tag */

#define HtmlifyTranslateNewlines  0x0002

/* translate tabs - converts each \t character to a <tab> tag */

#define HtmlifyTranslateTabs      0x0004

/* 

 *   Translate all whitespace characters - translate all spaces, tabs, and

 *   newlines into their HTML equivalents: each space character becomes an

 *   '&nbsp sequence;', each '\n' character becomes a <br> tag; and each

 *   '\t' character becomes a <tab> tag.  

 */

#define HtmlifyTranslateWhitespace \

    (HtmlifyTranslateSpaces | HtmlifyTranslateNewlines | HtmlifyTranslateTabs)

/*

 *   Flags for String.findReplace 

 */

/* replace only one occurrence, or replace all occurrences */

#define ReplaceOnce  0x0000

#define ReplaceAll   0x0001

/* ------------------------------------------------------------------------ */

/*

 *   The native list type 

 */

intrinsic class List 'list/030007': Collection

{

    /* 

     *   Select a subset of the list: returns a new list consisting only

     *   of the elements for which the callback function 'func' returns

     *   true.  

     */

    subset(func);

    /*

     *   Apply the callback function to each element of this list, and

     *   return a new list consisting of the results.  Effectively maps

     *   the list to a new list using the given function.  Suppose the

     *   original list is

     *   

     *   [x, y, z]

     *   

     *   Then the result list is

     *   

     *   [func(x), func(y), func(z)] 

     */

    mapAll(func);

    /* get the number of elements in the list */

    length();

    /* extract a sublist */

    sublist(start, len?);

    /* intersect with another list */

    intersect(other);

    /* get the index of the first match for the given value */

    indexOf(val);

    /* car/cdr - head/tail of list */

    car();

    cdr();

    /* 

     *   Find the first element for which the given condition is true, and

     *   return the index of the element.  Applies the callback function

     *   (which encodes the condition to evaluate) to each element in

     *   turn, starting with the first.  For each element, if the callback

     *   returns nil, proceeds to the next element; otherwise, stops and

     *   returns the index of the element.  If the callback never returns

     *   true for any element, we'll return nil.  

     */

    indexWhich(cond);

    /* 

     *   Invoke the callback func(val) on each element, in order from first

     *   to last.  No return value.  

     */

    forEach(func);

    /* 

     *   Find the first element for which the given condition is true, and

     *   return the value of the element.  Returns nil if no item

     *   satisfies the condition.  

     */

    valWhich(cond);

    /* find the last element with the given value, and return its index */

    lastIndexOf(val);

    /* 

     *   Find the last element for which the condition is true, and return

     *   the index of the element.  Applies the callback to each element

     *   in turn, starting with the last element and working backwards.

     *   For each element, if the callback returns nil, proceeds to the

     *   previous element; otherwise, stops and returns the index of the

     *   element.  If the callback never returns true for any element,

     *   we'll return nil.  

     */

    lastIndexWhich(cond);

    /* 

     *   Find the last element for which the condition is true, and return

     *   the value of the element 

     */

    lastValWhich(cond);

    /* count the number of elements with the given value */

    countOf(val);

    /* count the number of elements for which the callback returns true */

    countWhich(cond);

    /* get a new list consisting of the unique elements of this list */

    getUnique();

    /* 

     *   append the elements of the list 'lst' to the elements of this

     *   list, then remove repeated elements in the result; returns a new

     *   list with the unique elements of the combination of the two lists 

     */

    appendUnique(lst);

    /* 

     *   append an element - this works almost exactly like the

     *   concatation operator ('+'), but if the argument is a list, this

     *   simply adds the list as a new element, rather than adding each

     *   element of the list as a separate element 

     */

    append(val);

    /* 

     *   Sort the list, returning a new list.  If the 'descending' flag is

     *   provided and is not nil, we'll sort the list in descending order

     *   rather than ascending order.

     *   

     *   If the 'comparisonFunction' argument is provided, it must be a

     *   callback function; the callback takes two arguments, and returns

     *   an integer less than zero if the first argument value is less

     *   than the second, zero if they're equal, and an integer greater

     *   than zero if the first is greater than the second.  If no

     *   'comparisonFunction' argument is provided, or it's provided and

     *   its value is nil, we'll simply compare the list elements as

     *   ordinary values.  The comparison function can be provided for

     *   caller-defined orderings, such as ordering a set of objects.  

     */

    sort(descending?, comparisonFunction?);

    /*

     *   Prepend an element - this inserts the value before the first

     *   existing element. 

     */

    prepend(val);

    /* 

     *   Insert one or more elements at the given index.  If the index is 1,

     *   the elements will be inserted before the first existing element.

     *   If the index is one higher than the number of elements, the

     *   elements will be inserted after all existing elements.

     *   

     *   Note that a list value argument will simply be inserted as a single

     *   element.

     *   

     *   Returns a new list with the value(s) inserted.  

     */

    insertAt(startingIndex, val, ...);

    /*

     *   Delete the element at the given index, reducing the length of the

     *   list by one element.  Returns a new list with the given element

     *   removed.  

     */

    removeElementAt(index);

    /*

     *   Delete the range of elements starting at startingIndex and ending

     *   at endingIndex.  The elements at the ends of the range are included

     *   in the deletion.  If startingIndex == endingIndex, only one element

     *   is removed.  Returns a new list with the given element range

     *   removed.  

     */

    removeRange(startingIndex, endingIndex);

    /*

     *   Invoke the callback func(index, val) on each element, in order from

     *   first to last.  No return value.  

     */

    forEachAssoc(func);

}

/*

 *   Sorting order flags.  These can be passed in as the first argument to

 *   List.sort() (and Vector.sort() as well) to make the meaning of the

 *   argument clearer.  

 */

#define SortAsc    nil

#define SortDesc   true

/* ------------------------------------------------------------------------ */

/*

 *   'RexPattern' intrinsic class.  This class encapsulates a compiled

 *   regular expression pattern.

 *   

 *   A RexPattern object can be passed to the regular expression functions

 *   (rexMatch, rexSearch, rexReplace) in place of a string pattern.  Since

 *   compiling a regular expression takes a non-trivial amount of time, it's

 *   more efficient to compile a pattern to a RexPattern object if the same

 *   pattern will be used in multiple searches.  

 */

intrinsic class RexPattern 'regex-pattern/030000': Object

{

    /*

     *   Constructor:

     *   

     *   new RexPattern(patternString) - returns a RexPattern representing

     *   the compiled pattern string.  

     */

    /* retrieve the original pattern string used to construct the object */

    getPatternString();

}