Slag Plasmacore Reference v0.22

Class AltPatternMatcher

Internal use.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
next : PatternMatcher terms : PatternMatcher[]

Object Methods

chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init() init( PatternMatcher p1, PatternMatcher p2 ) init( PatternMatcher p1, PatternMatcher p2, PatternMatcher p3 ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class AnyMatcher

Internal use.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
max_count : Int32 min_count : Int32 next : PatternMatcher

Object Methods

chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( [Int32 min_count], [Int32 max_count] ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class Application

The base class for every Plasmacore game or application. Extend your game class from this class and override methods as warranted. Start with init(), update(), and draw().

Class Methods

close_all_archives() Closes all archives cached by open_archive() and frees the memory used by them. create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise exit_program() Causes the native framework to immediately exit the application. Typically called from on_exit_request(), but may be called independently. Example: Application.exit_program mouse_capture( Boolean setting ) Property-set that specifies whether the mouse is captured by (and restricted to) this application in windowed mode. This is "false" by default. Example: Application.mouse_capture = true mouse_visible( Boolean setting ) Property-set that specifies the visibility of the system mouse. This is "true" by default. Example: Application.mouse_visible = false open_archive( String filename ) Attempts to locate and load the named ZIP file into memory. The archive is not uncompressed when loaded. Subsequent attempts to open any file for reading (including loading images and sounds) will first check and see if the file is in any of the archives that have been opened with open_archive(). If found, the file is uncompressed and read from the archive. If not found, Plasmacore searches for the file in the regular filesystem. If 'filename' is, for example, "images", Plasmacore will attempt to open the archive using the following paths: images images.zip data/images data/images.zip Any number of archives may be opened concurrently - all of them are searched when a file is requested. Call close_all_archives() to close the archives and free up the memory used by them. Using archives in this fashion allows for a clean and compact distribution with no significant difference in loading speed on the Windows Plasmacore platform. However, writing games to utilize the archive system should yield speed benefits on platforms (e.g. Wii) where I/O seek time and data transfer rates are an issue (such as reading data off optical drive or over the network). Note when opening input files (including loading images and sounds), the following variations of the filename are automatically checked: filename filename.ext (ext = png, jpg, etc. as appropriate) data/filename data/filename.ext This means that when creating this new image object: Image("images/sprites"), the file "sprites.png" could either be located under "data/images/sprites.png" or under "images/sprites.png" in the archive "data/images.zip". WARNING: once again, open_archive does not simply add a search path to the zip file on disc - it actually loads the entire file into memory! window_title( String title ) Window title property-set for this application. Example: Application.window_title = "MadStone"

Object Methods

call_draw( Int32 window_width, Int32 window_height ) Internal use. Wraps a call to draw() in a try/catch block. call_init( Int32 display_width, Int32 display_height ) Internal use. Wraps a call to init() in a try/catch block. call_update() Internal use. Wraps a call to update() in a try/catch block. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. draw() Redraws the game. Called up to 60 times per second. You should not change the game's data model at this point. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init() Called to set up the game. Do not call any drawing operations at this point. listen_to( DispatcherType dispatcher ) Instructs this JoystickListener to listen to the given dispatcher. on_exit_request() Called when the user presses the close window button. Calls exit_program() by default. You can override this method to perform cleanup and/or postpone the call to exit_program at some later point. on_joystick_button_press( JoystickEvent event ) See JoystickEvent for more information. on_joystick_button_release( JoystickEvent event ) See JoystickEvent for more information. on_joystick_hat_movement( JoystickEvent event ) See JoystickEvent for more information. on_joystick_movement( JoystickEvent event ) See JoystickEvent for more information. on_key_press( KeyEvent event ) Called when a key is pressed. An on_keystroke() event is generated at the same time. If the key is held down for a while, key repeat events are sent as additional on_keystroke() events. 'event' contains information about the key. on_key_release( KeyEvent event ) Called when a key is released. 'event' contains information about the key. on_keystroke( KeyEvent event ) Called when a key has either been pressed and released or is pressed and is repeating. 'event' contains information about the key. on_mouse_absent() Called when the the game window loses mouse focus. on_mouse_button_press( MouseEvent event ) Called when a mouse button has been pressed. 'event.button' contains the index of the mouse button being pressed (1=left, 2=right). 'event.position' contains the absolute mouse position at the time of the press. on_mouse_button_release( MouseEvent event ) Called when a mouse button has been pressed. 'event.button' contains the index of the mouse button being pressed (1=left, 2=right). 'event.position' contains the absolute mouse position at the time of the press. on_mouse_movement( MouseEvent event ) Called when the mouse position changes. 'event' contains the new mouse position in relative (delta) coordinates. on_mouse_position() is also called with the new absolute position. on_mouse_position( MouseEvent event ) Called when the mouse position changes. 'event' contains the new mouse position in absolute coordinates. on_mouse_movement() is also called with the relative position change. on_mouse_present() Called when the mouse focus returns to the game window after being elsewhere. on_mouse_wheel_down( MouseEvent event ) Called when the mouse wheel has been rotated one click down. 'event.position' contains the absolute mouse position at the time of the wheel movement. on_mouse_wheel_up( MouseEvent event ) Called when the mouse wheel has been rotated one click up. 'event.position' contains the absolute mouse position at the time of the wheel movement. on_toggle_fullscreen() Called by the input object when an ALT+ENTER key combination is detected. The default behavior is to toggle the fullscreen property setting. on_trackball_movement( JoystickEvent event ) See JoystickEvent for more information. stop_listening_to( DispatcherType dispatcher ) Stops this JoystickListener from listening to the given dispatcher. to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String update() Called 60 times per second guaranteed. Do not perform any drawing actions; just update the world's data model.

Class ArbitraryCountPatternMatcher

Internal use.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
max_count : Int32 min_count : Int32 next : PatternMatcher term : PatternMatcher

Object Methods

chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). find_matches( PatternMatchInfo state ).Boolean hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( PatternMatcher term, [Int32 min_count], [Int32 max_count] ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class Array<<DataType>>

Primarily for internal use - in most cases use ArrayList instead.

Array is a placeholder type. Arrays are actually implemented in the runtime implementation; calls to array methods are intercepted by the program loader and translated into array-related opcodes.

The exception to this is when a call is made to an array using a reference of aspect types Readable or IndexedData - the loader is unable to intercept. However, the Slag-side implementation of each array simply calls itself, and *that* call *is* intercepted by the compiler.

To get an array in Slag you must be explicit, e.g. "Array<<Int32>>(20)". Convenience notation (such as Array[20]) generates ArrayLists instead.

Arrays are not covariant as they are in Java. An Array<<String>> counts as an Object but not as an Array<<Object>>.

Arrays may be extended or augmented but no new object variables may be added.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Methods

clear( Int32 first_index, Int32 last_index ) Clears all the elements in this array between the two indices. Using this method to clear elements at the end of an arraylist allows the runtime to limit the number of reference array elements it searches through during a data collection. Technical note: the runtime tracks the furthest position that a non-null reference array element could possibly be at after various calls to clear() and set(). compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. contains( DataType value ).Boolean Returns "true" if this data contains the given value. copy_elements( ArrayType src_array, Int32 src_index, Int32 dest_index, Int32 number ) Copies 'number' elements from another array (starting at element 'src_index') into this one (starting at element 'dest_index'). count().Int32 Returns the count of how many elements are in this array. create_duplicate().Array<<DataType>> Creates a duplicate of this array when the "duplicate(array)" command is given. If the array element type is a reference type, the new array contains a copy of the same references to the same objects - the objects themeselves are not duplicated. create_reader().Reader<<DataType>> Returns a reader that can be used to read() this data one element at a time. end( Int32 from_end ).DataType Equivalent to get( (count-1) + from_end ). For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2). equals( Readable<<DataType>> other ).Boolean Returns true if each element of this data equals() each corresponding element from in 'other'. equals( DataType value ).Boolean[] Returns a list of Boolean values where each value true if the corresponding element of this indexed data equals() the given value. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). first().DataType Returns the first element of this data. This convenience method is equivalent to get(0). get( Readable<<Boolean>> flags ).DataType[] Returns a new list containing the subset of elements of which each of the corresponding 'flags' is true. Example: local Int32[] nums = {1..10} println( nums[nums % 2 == 0] ) #prints: {2,4,6,8,10} get( Readable<<Int32>> indices ).DataType[] Gets the element at each of the given zero-based 'indices'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} get( Int32 index ).DataType Retieves the element at the zero-based 'index'. Requires: 0 <= index < count hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf index_of( DataType value, [Int32 starting_index] ).Int32 Returns the first index that the given value occurs at starting at index 0 by default. (-1) is returned if 'value' is not found. indices().Range<<Int32>> Returns this data's range of indices (0..count-1). init( Int32 size ) Sets up this array to contain the given number of elements. is_empty().Boolean Returns true if count == 0. is_not_empty().Boolean Returns true if count > 0. last().DataType Returns the last element of this data. This convenience method is equivalent to get(count-1). last_index_of( DataType value, [Int32 starting_index] ).Int32 Returns the last index that the given value occurs at starting at index (count-1) by default. (-1) is returned if 'value' is not found. modification_count().Int32 Returns a counter representing the number of times items has been added to or removed. Used by readers to detect concurrent list modification errors. For example, when an inner method removes an item from a list the modification counter is incremented. An outer "forEach" loop will detect that the count is different from its original value and throw a ConcurrentListModification error. random().DataType Returns an element of this data at random. reverse() Reverses the order of the elements in this data. reverse_indices().Range<<Int32>> Returns this data's range of indices reversed (count-1 downTo 0). Example: local Int32[] nums = {5..7} forEach (i in nums.reverse_indices) println( i ) #prints: 2 | 1 | 0 set( Readable<<Boolean>> element_flags, Readable<<DataType>> values ) Starting at index 0, sets each element to the next of the given 'values' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = -nums println( nums ) #prints: {-1,2,-3,4,-5} set( Int32 index, DataType value ) Sets the element at the zero-based 'index' to the new 'value'. Requires: 0 <= index < count set( Readable<<Int32>> indices, DataType value ) Sets the element at each of the given 'indices' to the given 'value'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} set( Readable<<Boolean>> flags, DataType value ) Starting at index 0, sets each element to the given 'value' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = 0 println( nums ) #prints: {0,2,0,4,0} set( Readable<<Int32>> indices, Readable<<DataType>> values ) Sets the element at each of the given 'indices' to each of the corresponding 'values'. Requires: The number of indices == the number of values. Example: local Int32[] nums = {1..5} nums[0..4 step 2] = {7,8,9} println( nums ) #prints: {7,2,8,4,9} shuffle() Swaps every element of this data with another element at a randomly-chosen position. subset( Int32 first_index, Int32 last_index ).ArrayList<<DataType>> Returns the subset of this data between indices [first_index,last_index] inclusive. swap( Int32 index_a, Int32 index_b ) Swaps the value at 'index_a' with the one at 'index_b'. Requires: 0 <= index_a < count 0 <= index_b < count Invariant: this[index_a] = old[index_b] this[index_b] = old[index_a] to_List().DataType[] Converts this data into a list. to_String().String Returns a string representation of this data. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class ArrayList<<DataType>>

The most common "collection" type in Slag, an ArrayList is an indexable list of items implemented using arrays.

An array list has 'count' and 'capacity'. Capacity is how many elements an arraylist can store before it has to create a larger backing array. Count is how many elements of the current array are currently in use. When 'count' reaches 'capacity', the next add() operation causes the backing array to be doubled in size.

An arraylist starts out at capacity 10, count 0 by default.

When you use "array notation" in Slag it creates arraylists. The following convenience conversions are performed:

  # Create an empty list with 10 capacity
  Int32[] nums(10)  # 10 capacity
    -> List<<Int32>> nums = ArrayList<<Int32>>(10)
  # Create a list of 10 zero/null values
  Int32[] nums = Int32[10]
    -> List<<Int32>> nums = ArrayList<<Int32>>( 10, 0 )
  # Create a list with the numbers 1 to 3
  Int32[] nums = { 1, 2, 3 }
    -> List<<Int32>> nums = ...
           ArrayList<<Int32>>().add(1).add(2).add(3)

  count >= 0
  capacity >= count
  data.count == capacity

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
counter : Int32 The position to add the next item - also equivalent to the used item count. data : Array<<DataType>> The backing array for this arraylist. modification_count : Int32

Object Methods

add( DataType value ).ArrayList<<DataType>> Adds the given 'value' to the end of this list. Returns a reference to this list for call chaining. Invariant: count = old.count + 1 get[count-1] == value add( Readable<<DataType>> source ).List<<DataType>> Adds each item from the Readable source to this list. Returns a reference to this list for call-chaining. add( DataType value, Int32 after_index ).List<<DataType>> Inserts 'value' after the given index. Returns: A reference to this list for call-chaining. Requires: after_index >= -1 and after_index < count Invariant: new.count == old.count + 1 new[after_index+1] == value capacity().Int32 Returns how many values this list can store before its backing array must be doubled in size. clear() Removes all elements from this list. The capacity is unchanged. Invariant: new.count == 0 new.capacity == old.capacity compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. contains( DataType value ).Boolean Returns "true" if this data contains the given value. count().Int32 Returns how many values there are in this list. create_duplicate().ArrayList<<DataType>> Creates a duplicate of this list when the "duplicate(list)" command is given. If the list element type is a reference type, the new list contains a copy of the same references to the same objects - the objects themeselves are not duplicated. Results: A duplicate list such that "all(this is result)" equals true. create_reader().Reader<<DataType>> Returns a reader that can be used to read() this data one element at a time. discard( Int32 first_index, [Int32 last_index] ) Removes the elements in the specified range. Does not return the list of removed elements like remove() does. If only the 'first' parameter is given, elements from 'first' to the end of the list are discarded. 'first' and 'last' are clipped to be a valid range. discard( Range<<Int32>> range ) Removes elements in the specified range. Requires: range.is_contiguous_ascending end( Int32 from_end ).DataType Equivalent to get( (count-1) + from_end ). For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2). ensure_capacity( Int32 min_capacity ) Effects that this list has a capacity of at least 'min_capacity'. If it has a lower capacity, the backing array is reallocated to have the necessary capacity. equals( DataType value ).Boolean[] Returns a list of Boolean values where each value true if the corresponding element of this indexed data equals() the given value. equals( Readable<<DataType>> other ).Boolean Returns true if each element of this data equals() each corresponding element from in 'other'. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). expand_to_capacity().ArrayList<<DataType>> Effectively adds enough null/zero values to this arraylist so that the count matches the capacity. Technically the backing array is maintained with null/zero values and so a counter is adjusted. Returns: A reference to this list for call chaining. Invariant: count == capacity first().DataType Returns the first element of this data. This convenience method is equivalent to get(0). get( Readable<<Int32>> indices ).DataType[] Gets the element at each of the given zero-based 'indices'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} get( Int32 index ).DataType Returns the element at the given zero-based index. Requires: 0 <= index and index < count get( Readable<<Boolean>> flags ).DataType[] Returns a new list containing the subset of elements of which each of the corresponding 'flags' is true. Example: local Int32[] nums = {1..10} println( nums[nums % 2 == 0] ) #prints: {2,4,6,8,10} hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf index_of( DataType value, [Int32 starting_index] ).Int32 Returns the first index that the given value occurs at starting at index 0 by default. (-1) is returned if 'value' is not found. indices().Range<<Int32>> Returns this data's range of indices (0..count-1). init( Int32 initial_capacity ) Creates an empty arraylist with a specified initial capacity. init( Readable<<DataType>> readable ) Initializes this list to contain all the items from the 'readable' data source. init() Creates an empty arraylist of capacity 10. init( Int32 initial_capacity, DataType content ) Creates an array list full of 'initial_capacity' duplicates of the given 'content'. insert( IndexedData<<DataType>> seq, [Int32 before_index] ).ArrayList<<DataType>> Inserts all the given values in front of 'before_index'. Elements at 'begin_index' and higher are shifted over by one. Returns: A reference to this list for call chaining. Requires: 0 <= before_index and before_index <= count Invariant: this[before_index] = value this[before_index+seq.count] = old[before_index] count = old.count + seq.count insert( DataType value, [Int32 before_index] ).ArrayList<<DataType>> Inserts the 'value' in front of 'before_index'. Elements at 'begin_index' and higher are shifted over by one. Returns: A reference to this list for call chaining. Requires: 0 <= before_index and before_index <= count Invariant: this[before_index] = value this[before_index+1] = old[before_index] count = old.count + 1 is_empty().Boolean Returns true if count == 0. is_not_empty().Boolean Returns true if count > 0. last().DataType Returns the last element of this data. This convenience method is equivalent to get(count-1). last_index_of( DataType value, [Int32 starting_index] ).Int32 Returns the last index that the given value occurs at starting at index (count-1) by default. (-1) is returned if 'value' is not found. modification_count().Int32 Returns a counter representing the number of times items has been added to or removed. Used by readers to detect concurrent list modification errors. For example, when an inner method removes an item from a list the modification counter is incremented. An outer "forEach" loop will detect that the count is different from its original value and throw a ConcurrentListModification error. random().DataType Returns an element of this data at random. remove( DataType value ).Boolean Calls remove_value(value). Only available for non-numerical lists - see note in remove_value(). remove( Int32 first_index, Int32 last_index ).DataType[] Removes and returns the elements in the specified range. 'first' and 'last' are clipped to be a valid range. Returns: The list of elements from old[first] through old[last]. remove( Range<<Int32>> range ).DataType[] Removes and returns the elements in the specified range. See discard() for a variant that's optimal when you don't need the return value. Requires: range.is_contiguous_ascending remove( Int32 index ).DataType Removes and returns the element at position 'index'. All elements higher than 'index' are shifted down by one spot and the list count is decremented. Returns: old[index] Requires: 0 <= index and index < count Invariant: new[index] = old[index+1] remove_first().DataType Equivalent to: list.remove(0) remove_last().DataType Equivalent to: list.remove(list.count-1) remove_value( DataType value ).Boolean Removes the first occurrence of 'value' from the list. Returns: "true" if an occurrence of 'value' was found and removed, or "false" if it was not found. Technical note: this method can't be named remove() because in an Int32[] list, remove(index) and remove(value) would have the same signature. reverse() Reverses the order of the elements in this data. reverse_indices().Range<<Int32>> Returns this data's range of indices reversed (count-1 downTo 0). Example: local Int32[] nums = {5..7} forEach (i in nums.reverse_indices) println( i ) #prints: 2 | 1 | 0 set( Readable<<Int32>> indices, Readable<<DataType>> values ) Sets the element at each of the given 'indices' to each of the corresponding 'values'. Requires: The number of indices == the number of values. Example: local Int32[] nums = {1..5} nums[0..4 step 2] = {7,8,9} println( nums ) #prints: {7,2,8,4,9} set( Int32 index, DataType value ) Sets the element at the given zero-based index. Requires: 0 <= index and index < count set( Readable<<Boolean>> flags, DataType value ) Starting at index 0, sets each element to the given 'value' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = 0 println( nums ) #prints: {0,2,0,4,0} set( Readable<<Boolean>> element_flags, Readable<<DataType>> values ) Starting at index 0, sets each element to the next of the given 'values' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = -nums println( nums ) #prints: {-1,2,-3,4,-5} set( Readable<<Int32>> indices, DataType value ) Sets the element at each of the given 'indices' to the given 'value'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} shuffle() Swaps every element of this data with another element at a randomly-chosen position. sort( [SORT_ORDER order] ) Sorts this list in place using a HeapSort. 'order' is SORT_ORDER.ascending by default. Only implemented for numerical and String lists. To enable it for lists of other types (say, Event), add this augment: augment List<<Event>> METHODS method sort( SORT_ORDER order=SORT_ORDER.ascending ): HeapSort<<DataType>>.sort( this, order ) endAugment subset( Int32 first_index, Int32 last_index ).ArrayList<<DataType>> Returns the subset of this data between indices [first_index,last_index] inclusive. swap( Int32 index_a, Int32 index_b ) Swaps the value at 'index_a' with the one at 'index_b'. Requires: 0 <= index_a < count 0 <= index_b < count Invariant: this[index_a] = old[index_b] this[index_b] = old[index_a] to_List().DataType[] Satisifies the ListAdaptable aspect of the IndexedData aspect by returning this list with no modifications. to_String().String Returns a string representation of this data. trim_to_count().ArrayList<<DataType>> Resizes the backing array to exactly fit the values currently stored in this list. Only recommended when memory usage is a concern and you won't be adding additional elements in the near future. Returns: A reference to this list for call chaining. Invariant: capacity == count type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class ArrayType

Placeholder class that provides a common base type for all Array<<DataType>> classes.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Methods

clear( Int32 first_index, Int32 last_index ) Clears all the elements in this array between the two indices. Using this method to clear elements at the end of an arraylist allows the runtime to limit the number of reference array elements it searches through during a data collection. Technical note: the runtime tracks the furthest position that a non-null reference array element could possibly be at after various calls to clear() and set(). compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. copy_elements( ArrayType src_array, Int32 src_index, Int32 dest_index, Int32 number ) Copies 'number' elements from another array (starting at element 'src_index') into this one (starting at element 'dest_index'). count().Int32 Returns the count of how many elements are in this array. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class BeginTagGroupPatternMatcher

Internal use.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
next : PatternMatcher tag_group_index : Int32

Object Methods

chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( Int32 tag_group_index ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Aspect BitFlags<<EnumType>>

Incorporate this aspect into enumerated types associated with Int32 values that define bit flags.

For example:

  enum DIRECTION : BitFlags<<DIRECTION>>
    CATEGORIES
      north(1), east(2), south(4), west(8)
  endEnum
  ...
  local DIRECTION d = DIRECTION.north | DIRECTION.east
  println( d == DIRECTION.north )         #prints: false
  println( d.includes(DIRECTION.north) )  #prints: true
  println( d )        #prints: north,east
  println( d.flags )  #prints: 3
  d &= !DIRECTION.north
  println( d )  #prints: east
  println( d == DIRECTION.east )  #prints: true
  println( d.flags )  #prints: 2

Class Variables
default_next_flag : Int32

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
flags : Int32

Object Methods

compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( EnumType other ).Boolean equals( Object other ).Boolean equals( Int32 other_flags ).Boolean hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf includes( Int32 other_flags ).Boolean Returns "true" if this category contains any of the bitflags from 'other_flags'. includes( EnumType other ).Boolean Returns "true" if this category contains any of the bitflags from the 'other' category. init( Int32 flags ) init() op!().EnumType Returns a new category that contains the inverse of this category's bitflags. op&( EnumType other ).EnumType Returns a new category that contains the intersection of bitflags from this category and the 'other' category. op&( Int32 other_flags ).EnumType Returns a new category that contains the intersection of bitflags from this category and 'other_flags'. op|( Int32 other_flags ).EnumType Returns a new category that includes all the bitflags from this category and 'other_flags'. op|( EnumType other ).EnumType Returns a new category that includes all the bitflags from this category and the 'other' category. to_String().String Returns a string containing the names of all comma-separated categories included in this category's bitflags. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class BitReader

A BitReader wraps an existing Reader<<Char>> and is able to read in 1-bit to 32-bit values at a time under normal operations. There are special method variants capable of reading in 64-bit values.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
bit_buffer : Int64 Internal use. bit_count : Int32 Internal use. src : Reader<<Char>> The backing source of characters.

Object Methods

available().Int32 Returns the minimum number of additional values that can be immediately read from this reader. If the reader is exhausted or if it must block to peek or read next then the result will be 0. It is important to note that '0' does not necessarily mean the reader is exhausted. Many readers will report that they have 1 available even if there are thousands of values waiting to be read. The 'available' property should be used as an aide for buffer sizes and the like but should not be taken as an absolute size. close() Closes this reader as a source of input. Useful for file readers, but for most others this command does nothing. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. consume( DataType look_for ).Boolean Attempts to match and discard the next value from this reader, returning true, or else leaves the next value still pending and returns false. Returns: "true" if old.peek == look_for "false" if old.peek != look_for Invariant: if (old.peek == look_for) old.skip create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). fill_buffer( Int32 to_n_bits ) Internal use. has_another().Boolean Returns true if there are at least 8 bits left to read. See also: has_another(Int32) has_another( Int32 n_bits ).Boolean Returns true if there are at least 'n_bits' left to read. 'n_bits' must be 1..32. hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( Readable<<Char>> readable ) Initializes this BitReader to read from the given readable character data. init( Reader<<Char>> src ) Initializes this BitReader to read from the given character reader. is_exhausted().Boolean Returns "true" if this reader does not have another value or "false" if it does. peek( Int32 n_bits ).Int32 Returns the next 'n_bits' value that will be returned by read(n_bits). peek().Char Returns the next 8-bit value that will be returned by read(). peek_bit().Int32 Returns the bit of input that will be returned by read_bit. position().Int32 This optional property-read returns the zero-based read position of this reader. When a reader is first created position() returns 0. After a single read() it returns 1, and so on. Readers that don't implement this property will throw an UnsupportedMethodError when it's accessed. position( Int32 new_position ) This optional property-write sets the zero-based read position of this reader. When a reader is first created position() returns 0. After a single read() it returns 1, and so on. Readers that don't implement this property will throw an UnsupportedMethodError when it's accessed. read( Int32 n_bits ).Int32 Returns the next value of size 'n_bits', giving a value between 0 and n_bits-1. Example: ... if (bits.peek == 0b01011000) println( bits.read(3) ) # prints "2" (010) println( bits.read(2) ) # prints "3" (11) println( bits.read(3) ) # prints "0" (000) endIf read().Char Returns the next 8 bits as a Char. read_Int64().Int64 Returns the next 64 bits as an Int64 assumed to be in high-low byte order. read_Int64_low_high().Int64 Returns the next 64 bits as an Int64 assumed to be in low-high byte order. read_bit().Int32 Returns the next bit of input. read_line().String Reads and returns the next line of characters up to the next LF or CRLF. The CRLF characters are not part of the return value and are discarded. Only defined for Reader<<Char>>. read_list( Int32 size ).DataType[] Reads the next 'size' number of values and returns them in a list. Requires that there are at least 'size' number of values remaining to be read. read_low_high( Int32 n_bits ).Int32 Returns the next n_bits as a value. n_bits must be 16 or 32 bits. This method assumes that the first 8 bits to be read are the least significant byte of the answer (bits 7:1) and the last 8 bits are the most significant byte of the number (e.g. bits 31:24). Requires: n_bits == 16 or n_bits == 32 remaining().Int32 This optional property returns how many values remain to be read before the reader is exhausted. Not all readers can implement this property; those that don't will throw an UnsupportedMethodError when it's accessed. rewind() This optional method resets this reader so that the next read() will return the first value of the series. Readers that don't implement this property will throw an UnsupportedMethodError when it's accessed. skip( [Int32 skip_count] ) Discards exactly the next 'skip_count' number of values rather than reading them. If there are not enough values remaining then a NoNextValueError will be thrown from read(). This program fragment: local var a = reader.read reader.read reader.read local var b = reader.read is equivalent to this: local var a = reader.read reader.skip(2) local var b = reader.read to_List().DataType[] Creates and returns a list of all the remaining values of this reader. to_String().String Returns a string representation of this reader's values. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class BitWriter

A BitWriter wraps an existing Writer<<Char>> and allows arbitrarily-sized values of 1-32 bits to be written. 64-bit values may also be written using a separate call.

The bits are buffered and groups of 8 at a time (single bytes) are written to the backing Char writer.

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
bit_buffer : Int64 Internal use. bit_count : Int32 Internal use. dest : Writer<<Char>> The backing character writer that a BitWriter outputs to.

Object Methods

capacity().Int32 Returns the minimum number of additional values that can written with this writer, or (-1) for "unlimited". clean_up() Closes the writer. Base aspect Writer does not incorporate the RequiresCleanup interface, but types for writers that do this method will be called when there are no more references to the object. close() Flushes and closes this BitWriter. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). flush() If there are any buffered bits that haven't been written to the backing writer yet, flush() writes out enough zero bits to make eight total and writes the resulting byte of information. hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf holds_has_another().Boolean Returns true if at least one more value can be written with write(). init( Writable<<Char>> writable ) Initializes this BitWriter to output to the given writable object. init( Writer<<Char>> dest ) Initializes this BitWriter to output to the given writer. position().Int32 This optional property-read returns the zero-based write position. This will be "0" before anything is written, "1" after a single write(), and so on. Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed. position( Int32 new_pos ) This optional property-write sets the zero-based write position. It is up to the implementation to define how repositioning works with gaps and what happens to data at a later spot after a reposition to an earlier spot. Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed. skip( Int32 skip_count ) This optional method repositions the writer to be 'skip_count' values further along. If a writer does not implement the 'position' property then an UnsupportedMethodError will be generated when skip() is called. to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String write( Int32 value, Int32 n_bits ) Writes 'value' in 'n_bits' using high-low byte order. write( DataType value ) Outputs 'value' in an implementation-specific way. Requires: holds_has_another == true write( Char value ) Writes 'value' in 8 bits. write_Int64( Int64 value ) Writes 'value' in 64 bits using high-low byte order. write_Int64_low_high( Int64 value ) Writes 'value' in 64 bits using low-high byte order. write_bit( Int32 b ) Writes 'b' (0 or 1) as a single bit. write_low_high( Int32 value, Int32 n_bits ) Writes 'value' in 'n_bits' using low-high byte order. 'n_bits' must be 16 or 32. The least-significant byte is written first and the most significant byte is written last. Requires: n_bits == 16 or n_bits == 32

Class Bitmap

Pixel data wrapper for examining and manipulating image data. Many native layer implementations load textures as Bitmap objects first and then convert them into hardware-accelerated Images.

Class Methods

create( String filename ).Bitmap Creates a Bitmap containing the pixel data from the specified file. Currently only png and jpg files are supported. create_duplicate( Object existing ).Object This factory method initiates object duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise

Object Variables
data : Array<<Color>> Single-dimensional array of Color values. Values data[0 ..< width] are the first row, data[width ..< width*2] are the second row, and so on. height : Int32 The height of this bitmap, in pixels. width : Int32 The width of this bitmap, in pixels.

Object Methods

add_transparent_outline() Adjusts this bitmap's data to include a 1-pixel transparent black border on each edge. clear( [Color color] ) Clears all the pixels of this bitmap to be the given color or opaque black by default. clear_channel( Color color, Int32 channel_mask ) Clears a certain channel of this bitmap to the given color. Parameters: color The color to clear to. Only the bits of the AARRGGBB 'color' that correspond to the set bits in 'channel_mask' are copied. channel_mask A 32-bit AARRGGBB value where 1 bits indicate the color should be copied and 0 bits where it shouldn't. For example, to clear the alpha channel to a:128 without affecting the red, green, or blue color values: clear_channel( new_Color(0,0,0,128), 0xff000000 ) column_transparent( Int32 x ).Boolean Returns "true" if column 'x' (where x is 0 ..< width) contains completely transparent pixel values. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt' Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.compare_to(obj2) == eq) obj1.equals(obj2) == true obj1.hash_code == obj2.hash_code else obj1.equals(obj2) == false endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation throws an UnsupportedMethodError. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. draw( Int32 x, Int32 y ) For native layer debugging purposes. Performs a slow image draw using a draw_point() call per pixel. draw( Rect r, Color color, Boolean blend_alpha ) Draws the outline of the given rectangle in the given color, optionally performing alpha-blending (default: true). draw( Vector2 pos ) For native layer debugging purposes. See draw(Int32,Int32). draw_channel_to( Bitmap dest, Int32 x, Int32 y, Int32 channel_mask ) Draws selected bits of this bitmap to the destination. No alpha blending is performed. Parameters: dest A bitmap to draw to. Edge clipping is performed. x,y Where to place the top-left corner of this bitmap. channel_mask A 32-bit AARRGGBB value where 1 bits indicate the color should be copied and 0 bits where it shouldn't. For example, to copy this bitmap's alpha values without disturbing the color values of the image: draw_channel_to( dest, 0, 0, 0xff000000 ) draw_to( Bitmap dest, Vector2 pos, [Boolean blend_alpha] ) Draws this bitmap to the given destination bitmap. This is operation is performed in software and is not intended for heavy per-frame use. Parameters: dest A bitmap to draw to. Edge clipping is performed. pos Where to place the top-left corner of this bitmap. blend_alpha (default:true) Set to "true" if per-pixel alpha blending should be performed. Set to "false" to completely overrwrite destination pixels. draw_to( Bitmap dest, Int32 x, Int32 y, [Boolean blend_alpha] ) Draws this bitmap to the given destination bitmap. This is operation is performed in software and is not intended for heavy per-frame use. Parameters: dest A bitmap to draw to. Edge clipping is performed. x,y Where to place the top-left corner of this bitmap. blend_alpha (default:true) Set to "true" if per-pixel alpha blending should be performed. Set to "false" to completely overrwrite destination pixels. equals( Object other ).Boolean Returns true if this object is equivalant to another. The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIf Note that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). fill( Rect r, Color color, [Boolean blend_alpha] ) Fills the given rectangle with the given color, optionally performing alpha-blending [default: false]. hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant: if (obj1.hash_code != obj2.hash_code) obj1.equals(obj2) == false obj1.compare_to(obj2) != eq endIf if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( String filename ) Creates a Bitmap containing image data from the given png or jpeg file. init( Bitmap existing, Rect rect ) Creates a bitmap that's a given subset of an existing bitmap. init( Int32 width, Int32 height ) Creates a transparent black bitmap of the given width and height. init( Bitmap existing ) Creates a bitmap that's an exact duplicate of an existing bitmap. init( Bitmap existing, Vector2 top_left, Vector2 new_size ) Creates a bitmap that's a given subset of an existing bitmap. init( Vector2 pixel_size ) Creates a transparent black bitmap of the given size. non_transparent_region().Rect Returns a rectangle just large enough to enclose all pixels that aren't completely transparent. If the area of the resulting rectangle is zero then this bitmap is completely transparent. Invariant: result == intersection_of(old,result) region().Rect Returns the rectangular region occupied by this bitmap. The 'position' of the resulting rectangle is (0,0). row_transparent( Int32 y ).Boolean Returns "true" if row 'y' (where y is 0 ..< height) contains completely transparent pixel values. set( Bitmap existing ) Sets this bitmap to reference the same data as another existing bitmap. Note that the array of Color data is shared rather than duplicated. size().Vector2 Returns the two-dimensional size of this bitmap, in pixels. split_into_tiles( Int32 tiles_wide, Int32 tiles_high ).Bitmap[] Splits this Bitmap into an array of separate Bitmap tiles. Returns a list of Bitmap objects where index 0 is the top-left tile, index[tiles_wide-1] is the top-right tile, and so on. to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. type_name().String Returns the true class name of this object. Implemented by the runtime; you should not override this method. Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String

Class CastReader<<FromType,ToType>>

Wraps an existing Reader<<FromType>> and casts each value to ToType.

Example:

  local Real64[] nums = { 3.0, 3.5, 3.9, 4.0 }
  forEach (n in CastReader<<Real64,Int32>>(nums)) println(n)
    # prints: 3 3 3 4

  # Read "data.txt" into a byte buffer.
  local Byte[] buffer = CastReader<<Char,Byte>>(File("data.txt").create_reader).to_List

Class Methods
create_duplicate( Object existing ).Object This factory method initiates object duplicat