Publishing properties

- Procedure for publishing properties of GridLAB-D classes

Synopsis
gl_publish_variable(CLASS *oclass, PROPERTYTYPE type, const char *'name, size_t offset, ..., NULL);


 * Declarations

GL_ATOMIC(type,name); GL_STRUCT(type,name); GL_STRING(type,name); GL_ARRAY(type,name, size); GL_BITFLAGS(type,name);
 * 1) include "gridlabd.h"

size_t get_name_offset; gld_property get_name_property;
 * General accessors

type get_name; type get_name(gld_rlock& rlock); type get_name(gld_wlock& wlock); void set_name(type value); void set_name(type value, gld_wlock& wlock);
 * Atomic accessors

type get_name; type get_name(gld_rlock& rlock); type get_name(gld_wlock& wlock); void set_name(type value); void set_name(type value, gld_wlock& wlock);
 * Struct accessors

char* get_name; char* get_name(gld_rlock& rlock); char* get_name(gld_wlock& wlock); void set_name(char* value); void set_name(char* value, gld_wlock& wlock); char get_name(size_t n); char get_name(size_t n, gld_rlock& rlock); void set_name(char value, size_t n); void set_name(char value, size_t n, gld_wlock& wlock);
 * String accessors

type* get_name; type* get_name(gld_rlock& rlock); type* get_name(gld_wlock& wlock); void set_name(type* value); void set_name(type* value, gld_wlock& wlock); type get_name(size_t n); type get_name(size_t n, gld_rlock& rlock); void set_name(type value, size_t n); void set_name(type value, size_t n, gld_wlock& wlock);
 * Array accessors

type get_name(type mask=-1); type get_name(gld_rlock& rlock); type get_name(gld_wlock& wlock); void set_name(type value); void set_name_bits(type value); void clr_name(type value); void set_name(type value, gld_wlock& wlock);
 * Bitflag accessors

Description
The gl_publish_variable function is a variable argument list call used to publish the publicly accessible properties of a GridLAB-D class. The argument list must contain a least one property type, property name and property offset tuple. The property type must be one of the members of PROPERTYTYPE. The property name must be a const char * and the property offset must be size_t. The property list must be NULL terminated.

Additional options may be added after each property definition tuple. These options include


 * PT_INHERIT : This will include the properties of the parent class (if any) in searches of this class's properties.


 * PT_ACCESS, access : This allows you to set special access rights (see PROPERTYACCESS for details).


 * PT_FLAGS, flags : This allows you to set special property flags (see PROPERTYFLAGS for details).


 * PT_UNIT, "definition" : This allows you to set the units for double and complex properties.


 * PT_SIZE, size : This allows you to define an array of properties.


 * PT_EXTEND : This allows you to enlarge the class by the size of the property.


 * PT_EXTENDBY, bytes : This allows you to enlarge the class by the number of bytes given.


 * PT_DESCRIPTION, "description" : This allows you to provide a text description of the property for use in given users help (see --modhelp for details)


 * PT_KEYWORD, "name", value : This allows you to define one or more keyword values to associate with the property (see set and enumeration for details). Note that you must cast constants to appropriate built-in types to avoid argument alignment problems.

GL_ATOMIC
GL_ATOMIC types are used strictly for data types that can set as an atomic operation on all platforms.

GL_STRUCT
If the data type cannot be set as an atomic operation, you must use the GL_STRUCT declaration.

GL_STRING
Any data type that is a character array can be declared as GL_STRING to enable string accessors.

GL_ARRAY
Data types that are general arrays can be declared as GL_ARRAY to enable array accessors.

GL_BITFLAGS
Bitmap and bitflags integers can be declared as GL_BITFLAGS to enable bit set and clear accessors.

Example
The following example is taken from the [🇸🇮/trunk/assert assert] module:


 * Header file ([🇸🇮/trunk/assert/assert.h assert.h])

class g_assert : public gld_object { public: typedef enum {AS_INIT=0, AS_TRUE=1, AS_FALSE=2, AS_NONE=3} ASSERTSTATUS; GL_ATOMIC(ASSERTSTATUS,status) GL_STRING(char1024,target); GL_STRING(char32,part); GL_ATOMIC(PROPERTYCOMPAREOP,relation); GL_STRING(char1024,value); GL_STRING(char1024,value2); // ... };


 * Implementation file ([🇸🇮/trunk/assert/assert.cpp assert.cpp])

g_assert::g_assert(MODULE *module) {  // ...   if (gl_publish_variable(oclass, PT_enumeration,"status",get_status_offset,PT_DESCRIPTION,"desired outcome of assert test", PT_KEYWORD,"TRUE",(enumeration)AS_TRUE, PT_KEYWORD,"FALSE",(enumeration)AS_FALSE, PT_KEYWORD,"NONE",(enumeration)AS_NONE, PT_char1024, "target", get_target_offset,PT_DESCRIPTION,"the target property to test", PT_char32, "part", get_part_offset,PT_DESCRIPTION,"the target property part to test", PT_enumeration,"relation",get_relation_offset,PT_DESCRIPTION,"the relation to use for the test", PT_KEYWORD,"==",(enumeration)TCOP_EQ, PT_KEYWORD,"<",(enumeration)TCOP_LT, PT_KEYWORD,"<=",(enumeration)TCOP_LE, PT_KEYWORD,">",(enumeration)TCOP_GT, PT_KEYWORD,">=",(enumeration)TCOP_GE, PT_KEYWORD,"!=",(enumeration)TCOP_NE, PT_KEYWORD,"inside",(enumeration)TCOP_IN, PT_KEYWORD,"outside",(enumeration)TCOP_NI, PT_char1024, "value", get_value_offset,PT_DESCRIPTION,"the value to compare with for binary tests", PT_char1024, "within", get_value2_offset,PT_DESCRIPTION,"the bounds within which the value must bed compared", PT_char1024, "lower", get_value_offset,PT_DESCRIPTION,"the lower bound to compare with for interval tests", PT_char1024, "upper", get_value2_offset,PT_DESCRIPTION,"the upper bound to compare with for interval tests", NULL)<1) throw "assert property publish failed"; // ... }