Documentation for SOOP API Library v1.0
Table of Contents

Object Manipulation

Routines for Creating, Manipulating and Destroying Class Objects.


This is the core of the SOOP API Library. These functions are what allow you to do most of the work that is needed in a Object Oriented library.

  • func ClassType( sObj Instance )   Returns the Class Name of the Object Instance.
  • func method_call_back( eObj RoutineID, eInt ParamCount )   This creates a Method Call Back ID for use with External Libraries.
  • func method_func( sObj Instance, eSeq MethodName, eSeq Arguments )   Calls a Method on a Object Instance
  • func method_id( sObj Instance, eSeq MethodName )   Creates a Method ID on a Method declared on an Object Instance.
  • proc method_proc( sObj Instance, eSeq MethodName, eSeq Arguments)   Calls a Method on a Object Instance.
  • func new( sfStr ClassName, eSeq CreateArguments )   Creates a New object given by Class, and returns it's instance if successfully created.
  • func oallocate( sObj Instance )   Stores the Object Instance into Memory
  • func odecode( eSeq dat, sObj Instance )   Converts an Object Instance back from a ASCII Encoded Sequences Flat String.
  • func oencode( sObj Instance )   Converts an Object Instance into an ASCII Encoded Sequence Flat String.
  • func oget( sObj Instance, eSeq MemberName )   This returns the data stored in a Member of Object.
  • func olast( sObj Instance )   Returns the last data retrived with oget() on the object instance.
  • func opeek( eAtom MemoryAddress, sObj Instance)   Reads a Object Instance Data from a Memory Location
  • func oread( eAtom FileHandle, sObj Instance )   Reads a Object stored in a file, back into a Instance in Memory.
  • proc oset( sObj Instance, eSeq MemberName, eObj Value )   Stores data into a Member on a Object Instance.
  • proc owrite( eAtom FileHandle, sObj Instance )   Writes an Object Instance to File.
  • proc recycle( sObj Instance )   Destroys a Object Instance given.
  • func ValidObject( sObj Instance )   This function determins weither or not a Object is Valid.

    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    ClassType
    ( sObj Instance )

    Returns the Class Name of the Object Instance.

    Returns: String Class Name

    Category: Object Manipulation

    This returns the Class Name used to create the object instance given. This makes it easier to ensure that you are dealing with the right class or not.

    See Also: method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    method_call_back
    ( eObj RoutineID, eInt ParamCount )

    This creates a Method Call Back ID for use with External Libraries.

    Returns: Returns a Method Call Back ID

    Category: Object Manipulation

    Like it's counterpart, call_back(), this creates a Memory address, with assembly to be passed along to an External library, such as Dynamic Link Library, or Shared Object, dependant apon the platform your running on. This allows External libraries to utilize the SOOP Enviroment, without having to pass extra data to it. The External Library never needs to know which Object is being used by the SOOP library, in order to properly interact with it, since the information is stored locally. You must pass a valid method_id() to method_call_back() in order for it to work, and you can use '+' in a sequence pass for the ID, to declare a CDECL callback, instead of a STDCALL.

    See Also: ClassType, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    method_func
    ( sObj Instance, eSeq MethodName, eSeq Arguments )

    Calls a Method on a Object Instance

    Returns: Data from a Function

    Category: Object Manipulation

    This routine allows you to call a Method defined as an Euphoria function. It follows the same rules as call_func(), and the same structure as method_proc(). When using multiple refrences, it should be noted, that return values are returned in a sequence, in the order that they are exected.

    See Also: ClassType, method_call_back, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    method_id
    ( sObj Instance, eSeq MethodName )

    Creates a Method ID on a Method declared on an Object Instance.

    Returns: A Unique Method ID

    Category: Object Manipulation

    This function works in the same way that routine_id() does, however, it is meant for the SOOP Library only, as it works only with Methods declared on a Object. What this does, is creates a Unique ID from the Method Name, and Object Instance, in which to allow for the patched in versions of call_func()/call_proc() to utilize. The reason for this, is to allow other libraries, such as win32lib, or Allegro, to use the SOOP Enviroment, without any modification to thoes libraries. However, in order to allow SOOP's patched in versions of call_func()/call_proc(), you will need to include soop.e before any other library that you want to utilize this system.

    See Demo3.exw for an example.

    See Also: ClassType, method_call_back, method_func, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [proc]
    method_proc
    ( sObj Instance, eSeq MethodName, eSeq Arguments)

    Calls a Method on a Object Instance.

    Category: Object Manipulation

    This routine allows you to call a Method defined as an Euphoria procedure. It follows the same rules as call_proc() does, however instead of using a routine_id() as an argument to this, you use the method's name, as the caller. Multiple Methods can be called with this as well.

    Example:

    Class("MyClassA")
    procedure doSomething()
    puts(1,"Hello World!\n")
    end procedure
    Method("display1",routine_id("doSomething"))
    procedure doSomething2()
    puts(1,"How are you today?")
    end procedure
    Method("display2",routine_id("doSomething2"))
    EndClass()
    constant aba = new("MyClassA",{})
    method_proc(aba,{"display1","display2"},{{},{}})
    -- displays:
    -- Hello World!
    -- How are you today?
    

    See Also: ClassType, method_call_back, method_func, method_id, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    new
    ( sfStr ClassName, eSeq CreateArguments )

    Creates a New object given by Class, and returns it's instance if successfully created.

    Returns: Returns an Object Instance

    Category: Object Manipulation

    This function creates a new object instance of the class definition given by ClassName. CreateArguments are the arguments that are passed off to your Construct routine, which is executed after all the base data has been stored, allowing you to modify information as needed.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    oallocate
    ( sObj Instance )

    Stores the Object Instance into Memory

    Returns: Memory Location

    Category: Object Manipulation

    This converts the Object Instance data, into a ASCII String, and stores it into Memory, which can be used to send across the internet, or through other measures, in which to send or receive data. The same rules for this, applies as they do with owrite().

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    odecode
    ( eSeq dat, sObj Instance )

    Converts an Object Instance back from a ASCII Encoded Sequences Flat String.

    Returns: Object Instance

    Category: Object Manipulation

    This allows Object Instance data to be put back into an Object memory location, in the same form that it was written into. This function follows the same rules as oread() and opeek().

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, oencode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    oencode
    ( sObj Instance )

    Converts an Object Instance into an ASCII Encoded Sequence Flat String.

    Returns: Sequence Flat String

    Category: Object Manipulation

    This allows Object Instance data to be returned as an ASCII Encoded String, to the caller. This can be used to manipulate the data,or do various other things. This function operates in the same method and rules as owrite() and oallocate().

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oget, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    oget
    ( sObj Instance, eSeq MemberName )

    This returns the data stored in a Member of Object.

    Returns: Data stored in Member

    Category: Object Manipulation

    This allows for same name variables to be declared, and seperated by the instance object. It allows for data to be retrived of any type, and dependant apon the Data Type given, you can also retrive the pointer used by the Member.

    Example:

    Class("MyClassA")
    Member("Var1",STRING)
    EndClass()
    constant MyObj = new("MyClassA")
    oset(MyObj,"Var1","Hello World")
    c_proc(xSetWindowTitle,{hWnd,oget(MyObj,{"Hello World"})})
    -- The title of hWnd is now "Hello World", but is set via the Pointer returned by oget()
    

    Multiple refrences can also be passed to name, so you could do something like this:

    Class("Score")
    Member("Score",INTEGER)
    Member("Name",STRING)
    procedure Score_construct(sequence dat)
    oset(this,"Name",dat[1])
    oset(this,"Score",dat[2])
    end procedure
    Constructor(routine_id("Score_construct"))
    EndClass()
    constant Player = new("Score",{"Mario",32})
    printf(1,"%s's score is %d",oget(Player,{"Name","Score"}))
    -- Displays: "Mario's score is 32"
    

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, olast, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    olast
    ( sObj Instance )

    Returns the last data retrived with oget() on the object instance.

    Returns: Returns the data in a Member

    Category: Object Manipulation

    This function maybe useful, if you use the same member name, in a if elsif end if statement. It returns the last data retrived with oget().

    Example:

    Class("ClassA")
    Member("Platform",INTEGER)
    procedure Constructor_ClassA(sequence dat)
    oset(this,"Platform",platform())
    end procedure
    Constructor(routine_id("Constructor_ClassA"))
    EndClass()
    constant Platform = new("ClassA",{})
    if oget(Platform,"Platform",{}) then end if
    if olast(Platform) = DOS32 then
    puts(1,"You are running on DOS32 Euphoria.")
    elsif olast(Platform) = WIN32 then
    puts(1,"You are running on Win32 Euphoria.")
    elsif olast(Platform) = LINUX then
     puts(1,"You are running on Linux/FreeBSD Euphoria.") 
    end if
    

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, opeek, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    opeek
    ( eAtom MemoryAddress, sObj Instance)

    Reads a Object Instance Data from a Memory Location

    Returns: Object Instance

    Category: Object Manipulation

    This converst he Object Instance data in an ASCII String memory location, back into a Object Instance. This function follows the same rules as oread() does.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, oread, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    oread
    ( eAtom FileHandle, sObj Instance )

    Reads a Object stored in a file, back into a Instance in Memory.

    Returns: Object Instance

    Category: Object Manipulation

    This will read a Object Instance from a file, given by FileHandle, and store it back into the Object Memory, so that you can use it. Instance can be a valid Object, as long as it is the same class that is being read in, or you can supply 0 to indicate that a new instance to be created from the object data.

    Constructors are not executed if the oread() function must create a new instance.

    Classes that are members of the instance being read in, will get the data restored, or recreated, when the data is being read in.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oset, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [proc]
    oset
    ( sObj Instance, eSeq MemberName, eObj Value )

    Stores data into a Member on a Object Instance.

    Category: Object Manipulation

    This procedure allows you to store data of Value in a member given by MemberName, on an object given by Instance. Multiple refrences and values can be given.

    Example:

    Class("MyClassA")
    Member("Var1",INTEGER)
    Member("Var2",ATOM)
    EndClass()
    constant Obj = new("MyClassA",{})
    oset(Obj,{"Var1","Var2"},{32,#FFFFFF})
    

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, owrite, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [proc]
    owrite
    ( eAtom FileHandle, sObj Instance )

    Writes an Object Instance to File.

    Category: Object Manipulation

    This routine allows you to write a Object Instance's data to disk for later reading back into the program, or by another program. There's several thing to notes however, that when writting a objects data to disk Temporary data, such as Window Handles, Allocated Memory Pointers, and File handles will not be valid in another program, or not valid when you run the program again.

    Pointers from the Data Type system will never be written to file, the actual data stored in them will be though.

    Data Corruption can still happen. The library tries to detect as much as possible, but it's not a sure thing. It's reliable, but there's still a a chance that the data will get corrupt.

    Classes defined as Members will get their data structure also written to disk when the library writes the instance in question to disk.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, recycle, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [proc]
    recycle
    ( sObj Instance )

    Destroys a Object Instance given.

    Category: Object Manipulation

    This destroys the object instance given, and returns the memory used by the object to the library for future object instance creation. All Deconstructors that are attached to a object are executed at this time, and any method_id()'s used by this object also become invalid during this time.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, ValidObject


    Documentation for SOOP API Library v1.0
    Table of Contents

    [func]
    ValidObject
    ( sObj Instance )

    This function determins weither or not a Object is Valid.

    Returns: Boolean True or False

    Category: Object Manipulation

    It checks the Object memory space, to ensure that the object is a valid object, and returns true if it exists, or false if it doesn't exist. There's two ways that an Object may not exist. If the object has been removed from memory via the recycle procedure, or has not been created yet.

    See Also: ClassType, method_call_back, method_func, method_id, method_proc, new, oallocate, odecode, oencode, oget, olast, opeek, oread, oset, owrite, recycle