*bug cslib_object is a cslib module and must not be accessed directly

*comment cslib_object
*comment Allows the simple manipulation of arrays of sets of variables
*comment
*comment How it works:
*comment A object is always accessed through its main instance.
*comment When you "get" an instance of a object, the data for that particular instance 
*comment is copied into the main instance
*comment
*comment A object definition has the following elements defined in startup.txt:
*comment	1. A object "field" array defining all the field names
*comment		objectname_field_N field
*comment	2. A main instance of this object. This is used to 'return'
*comment		the object (similar to cslib_ret).
*comment	3. An array of instances of the object
*comment		
*comment Note: each object MUST have an objectname_id field
*comment This is not part of the object definition and only exists associated
*comment with the main instance.
*comment Its purpose is to 'return' the current index of the object, which
*comment is particularly useful for get_by_field.
*comment
*comment Public methods
*comment	get object index
*comment		copy the instance of the object at index into main instance
*comment	get_by_field object field value
*comment		copy the instance of the first object where the specified field
*comment		has the specified value into the main instance
*comment	set object index field value
*comment		set the specified field to the specified value in the instance
*comment		of the object at index
*comment
*comment ------------------------------------------------------------------
*comment EXAMPLE - startup.txt - object "dragon"
*comment 
*comment *create dragon_field_1 "name"
*comment *create dragon_field_2 "hp"
*comment *create dragon_field_max 2
*comment
*comment NOTE: dragon_id is a required field
*comment *create dragon_id ""
*comment *create dragon_name ""
*comment *create dragon_hp ""
*comment
*comment *create dragon_1_name "Wally"
*comment *create dragon_1_hp 100
*comment *create dragon_2_name "Dave"
*comment *create dragon_2_hp 150
*comment *create dragon_count 2
*comment
*comment EXAMPLE of getting a dragon instance
*comment
*comment *gosub_scene cslib_object get "dragon" 2
*comment 	sets dragon_name to "Dave" and dragon_hp to 150 and dragon_id to 2
*comment
*comment EXAMPLE of getting a dragon by matching field name and value
*comment
*comment *gosub_scene cslib_object get_by_field "dragon" "name" "Wally"
*comment 	sets dragon_name to "Wally" and dragon_hp to 100 and dragon_id to 1
*comment
*comment EXAMPLE of setting a dragon instance
*comment
*comment *gosub_scene cslib_object set "dragon" 2 "name" "Sir David"
*comment    sets dragon_2_name to "Sir David"
*comment	now when you get dragon 2, dragon_name will be "Sir David"
*comment	this will persist until you set it again

*comment GET
*comment ------------------------------------------------------------------
*comment Takes the instance of a object specified by the index and copies
*comment the data into the main instance
*comment ------------------------------------------------------------------
*comment
*comment params:
*comment	p_objectname (string): the name of the object
*comment	p_index (number): index of this object instance
*comment returns:
*comment	none
*comment usage example:
*comment 	*gosub_scene cslib_object get "dragon" 2
*comment ------------------------------------------------------------------

*label get
*params p_objectname p_index
*set cslib_ret ""
*gosub _set_main_instance p_objectname p_index
*return

*comment GET_BY_FIELD
*comment ------------------------------------------------------------------
*comment Takes the specified field name and field value and finds the
*comment first instance of a match that it finds and copies that data
*comment into the main instance
*comment If no match is found, a *bug is raised
*comment ------------------------------------------------------------------
*comment
*comment params:
*comment	p_objectname (string): the name of the object
*comment	p_field (string): field to match
*comment	p_value (string): value to match
*comment returns:
*comment	none
*comment usage example:
*comment 	*gosub_scene cslib_object get "dragon" "name" "Wally"
*comment ------------------------------------------------------------------

*label get_by_field
*params p_object p_field p_value
*set cslib_ret ""
*temp found_it false
*temp n 1
*temp array_count {p_object&"_count"}
*temp index ""
*label _get_by_field_main_loop
*if (n <= array_count)
	*if ({p_object&"_${n}_${p_field}"} = p_value)
		*set found_it true
		*goto _get_by_field_end_search
	*set n + 1
	*goto _get_by_field_main_loop
*label _get_by_field_end_search
*if (found_it)
	*gosub _set_main_instance p_object n
*else
	*bug cslib_object.get_by_field: Value of '${p_value}' not found for field '${p_field}' in object type '${p_object}'
*return

*comment SET
*comment ------------------------------------------------------------------
*comment Set the value of one or more fields in a particular instance of an object
*comment ------------------------------------------------------------------
*comment params:
*comment	p_objectname (string): the name of the object
*comment	p_index      (number): index of this object instance
*comment	param_n      (string): a field to update
*comment	param_n+1    (string): the value to update the prior field to
*comment returns:
*comment	none
*comment usage examples:
*comment 	*gosub_scene cslib_object set "dragon" 2 "name" "Bruce"
*comment 	*gosub_scene cslib_object set "dragon" 3 "hit_points" 200 "name" "Jack"
*comment ------------------------------------------------------------------

*label set
*params
*comment p_objectname p_index p_field_1 p_value_1 p_field_2 p_value_2 p_field_n p_value_n ...
*if ((param_count < 4) or ((param_count modulo 2) != 0))
    *bug cslib_object.set: Expected an even number of 4 or more parameters: 'p_objectname' and 'p_index' followed by at least 1 'field' 'value' pair, but got: '${param_count}' parameters
*temp p_objectname param_1
*temp p_index param_2
*temp p_param 3
*label _set_loop
*if (p_param < param_count)
    *temp p_field param[p_param]
    *temp p_value param[p_param+1]
    *set {p_objectname&"_${p_index}_${p_field}"} p_value
    *set p_param + 2
    *goto _set_loop
*set cslib_ret ""
*return

*comment ------------------------------------------------------------------
*comment --- PRIVATE METHODS
*comment ------------------------------------------------------------------

*comment --- ------------------------------------------------------------------
*comment --- Copies the values in the instance at the given index into the main instance
*comment --- ------------------------------------------------------------------
*label _set_main_instance
*params p_object p_index
*temp n 1
*temp field_count {p_object&"_field_max"}
*temp tempfield ""
*set {p_object&"_id"} p_index
*label _set_main_loop
*if (n <= field_count)
	*set tempfield {p_object&"_field_${n}"}
	*set {p_object&"_${tempfield}"} {p_object&"_${p_index}_${tempfield}"}
	*set n + 1
	*goto _set_main_loop
*return

*comment --- ------------------------------------------------------------------
*comment --- Sets all the fields of the main instance to the given value
*comment --- ------------------------------------------------------------------
*label _clear_main_instance
*params p_object
*params p_value
*temp n 1
*temp field_count {p_object&"_field_max"}
*temp field ""
*set {p_object&"_id"} p_value
*label _clear_main_loop
*if (n <= field_count)
	*set field {p_object&"_field_${n}"}
	*set {p_object&"_${field}"} p_value
	*set n + 1
	*goto _clear_main_loop
*return