CapeSoft Reflection
Documentation

• Introduction
• Requirements
• ClarionLive
• Installation
• Jump Start
• Support
• License and Distribution
• AnyScreen
• Use in a Hand-Coded Project
• The Naming of Things
• Getting Started
• Using ReflectClass
• WHO versus Prop:Name
• Creating Tables
• Memos and Blobs
• Supported Field Types
• Examples
• Template Reference
  • Global Extension
• Class Reference
  • Properties
  • Methods
• Version History

The Reflection class allows generic code (libraries) to work on structures in a more powerful way. This is done through the use of Extended Name Attributes which are declared with the structure. These attributes can then be used so that libraries better understand the structure.

The Reflection class acts as a parser for the extended attributes layer, and also allows you to alter attributes at run time.

Because the extensive use of Reflection encourages libraries to support more complex data structures (queues-in- queues etc) the Reflection class also provides a number of Helper methods to perform common tasks that these libraries will need. For example DISPOSEing complex structures is complicated, so Reflection has a helper method which does that for you.

This is a required layer for some other CapeSoft Accessories, and is provided free of charge.

Reflection requires StringTheory 3.

An introduction to this class, and the way in which it works, was described in ClarionLive session #637 , recorded on 12 November 2021.

Run the supplied installation file.

Add the global extension to your app file.

Your questions, comments and suggestions are welcome. Check our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways:

CapeSoft Support
Email
Telephone	+27 87 828 0123 (087) 828 0123

No additional files are required for shipping.

The files in this product are copyright 2024 by CapeSoft.

This product is provided free of charge for the use by the Clarion community. It can be ordered (for free) from ClarionShop.

Other 3rd party suppliers are explicitly allowed to create their own libraries making use of this library.

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft , their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

For the full EULA see https://capesoft.com/eula.html

Reflection is a class product, and has no User Interface, so it is completely compatible with programs running under AnyScreen.

1. Add the line
   Include('Reflection.Inc'),Once
   to your project in the appropriate scope, so the class is in scope.
2. Set the Conditional Compile in your project
   ReflectionLM => 1
3. Set the Conditional Compile in your project
   ReflectionDM => 0

The word "name" is used rather casually when referring to a declaration. In order to properly understand the sections that follow, it is important to be precise in the usage.  The simplest Clarion declaration consists of a LABEL and a TYPE;

x  Long

This declaration has no NAME attribute. So in this situation the NAME of the field defaults to the UPPER CASE of the LABEL. So the NAME of this field is X.

Fields can be declared with a specific name;

s  String(255),Name('Title')

In this case the LABEL of the field is S (LABELS are ALWAYS UPPERCASE) and the NAME of the field is Title. (Names are always Case Sensitive.)

In the Clarion language LABELS have to be unique, NAMES do not have to be unique. However the ReflectClass identifies things based on their Structure Name (known as the GroupName) and the NAME (known as the ColumnName). So for the purposes of using the ReflectClass the NAME attribute has to be unique in the structure.

a1  String(255),Name('Address1')
a2  String(255),Name('Address2')
a3  String(255),Name('Address3')

In external data structures, like JSON and XML, these names translate into the TagNames used in those structures. However in those (and other) external structures, those TagNames do not need to be unique. For this reason the ReflectClass supports the Rename attribute.

a1  String(255),Name('Address1 | Rename(Address)')
a2  String(255),Name('Address2 | Rename(Address)')
a3  String(255),Name('Address3 | Rename(Address)')

But wait, there's more.

It is possible that one structure will be used to export data to multiple different formats. And conceptually these names may be different from one format to another. In this situation the declaration may look like this;

a1  String(255),Name('Address1 | Rename(Address) | XMLName(ADDR) | JsonName(address)')

In this case, when matching to XML (importing or exporting) it is ideal to use ADDR, when matching to JSON use address (lower case) and when matching to anything else use Address (mixed case). In order for the object to know which external tagname to use, a property called tag exists. This property can be set before parsing the structure. For example;

reflection  ReflectClass
  code
  reflection.tag = 'xmlname'

When this is set, and the structure is parsed, then the XMLName (if it exists) will be placed in the Rename Attribute for the field.

Hint: The Name attribute is limited to 100 characters long by the Clarion language.

The ReflectClass class is declared in Reflection.Inc and the code for the class is in Reflection.Clw. The goal of the class is to accept structures (Group, Queue, File and View) and to parse out their attributes, and extended attributes. This can then be used when writing generic functions.

A small template (Reflection.Tpl) is also provided for use in an App - This includes a global template for Activating the class in a program, and a Local template for instantiating instances of the class in procedures. Reflection can also be used in hand-coded projects, or included in other classes.

In most cases the use of ReflectClass will be simple;

1) Parse the structure

3) While looping through the records in the structure, use the GET methods to discover the attributes for the columns, and make the appropriate changes to input and output.

In more complex cases it's possible to include some more steps;

2) Add additional attributes to the columns in the structure using one or more of the SET methods.

4) Depending on your structures (especially queue-in-queue and queue-in-group nested structures) make use of the DISPOSE methods.

The class primarily takes in a structure, parses it, and then provides a number of methods for accessing the structure for use by the calling class.

The first step is to declare an object of the class.

Reflection  ReflectClass

The next step is to pass a structure to the class for parsing. A single object can manage the parsing for multiple different structures. To do this a Structure Name (known internally as the GroupName) is used with the Parse method.

HomeQueue      Queue
House            String(255),name('House')
Photo            &StringTheory,name('Photo | StringTheory | Binary')
Date             Long,name('Date | date | @d6')
Pets             &PetsQueueType,name('Pets | Queue | RowName(Pet) | Rename(xPets)')
               End 

PetsQueueType  Queue,type
id               Long,name('Id | attribute')
Name             Group,name('Name')
WholeName          String(20),name('WholeName')
NickName           String(20),name('Nickname | attribute')
                 End
               End

  code
  reflection.Start()
  reflection.Parse('homequeue',HomeQueue)

Structures may contain child queues. If these queues are assigned to something (ie not null) then they will be parsed when the parent is parsed. If they are null then they are not parsed and will need to be parsed later, when set to something.

Structures may contain child groups. These are parsed when the parent is parsed.

Once the structure has been parsed the items in the structure can be accessed using the GetAttributeExists and GetAttributeValue methods with a combination of the group name and column name.
The GetAttributeExists method will return rf:ok if the attribute exists, and rf:notok if it does not.

x = reflection.GetAttributeExists('homequeue','photo','binary')

If the attribute has a value (in other words it is of the form attribute(value) ) then use the GetAttributeValue method and the value will be returned.

s = reflection.GetAttributeValue('homequeue','pets','rowname')

You can specifically set an attribute using the SetAttribute method for a field in code - in other words supplementing the attributes in the declaration;

reflection.SetAttribute('homequeue','pets','req')

While most attributes can be accessed via the GetAttribute and SetAttribute methods, some attributes cannot, and are more easily obtained via specialized methods. These attributes are the PICTURE, TYPE and RENAME attributes. they are accessed using the GetPicture, GetType and GetRename methods.

p = reflection.GetPicture('homequeue','date')
t = reflection.GetType('homequeue','date')
r = reflection.GetRename('homequeue','pets')

These are matched with SetPicture, SetType and SetRename.

Helper Methods

Assigning Methods

Debugging Methods

There are fundamentally two ways to get the external field name for a field. The first is using the WHO function, and the second is using the Field{prop:Name} syntax. At first glance these appear to both return the same thing, but actually there is a slight difference between the two.

The WHO value is set when the program is compiled, and it cannot be changed at run time. It is Read-Only, and will not change during the life of the program.

The Prop:Name value is read/write. It can be written to at run time.

The Reflection class uses the WHO approach to parse the table, so the attributes there are fixed and are not writable. However additional attributes can be added to a structure using any of the SET methods.

Hint: The Name attribute is limited to 100 characters long by the Clarion language.

Creating Tables

Blobs and Memos

These are the Type attributes which are supported by the ReflectClass engine. Not all of these attributes will be applicable to, or supported by, libraries using the ReflectClass. Consult the library documentation to determine which attributes are supported. In some cases there are multiple attributes for the same equate to allow for programming naming preferences.

Attribute	Equate	Description
& , &*		See Reference
Any	rf:Any	Field is an ANY field.
BFloat4	rf:Bfloat4	Contains a Clarion BFloat4
BFloat8	rf:BFloat8	Contains a Clarion BFloat8
Bool, Boolean	rf:Boolean	Contains either True or False or 1 or 0.
Byte	rf:Byte	Contains a Clarion byte field, which can contain a number from 0 to 255.
CString	rf:Cstring	Field is a CString
&Cstring, CStringPtr	rf:CStringPtr	Field is a reference to a Cstring
CStringJson	rf:CstringJson	String contains valid JSON text.
CStringXml	rf:CStringXml	String contains valid XML text.
CStringJsonPtr	rf:CStringJsonPtr	Field contains a reference to a cstring, which contains valid JSON text.
CStringXmlPtr	rf:CStringXmlPtr	Field contains a reference to a cstring, which contains valid XML text.
Decimal	rf:Decimal	Field contains a decimal
DWord		See ULong
File, &File, Table, &Table	rf:Table	Field is a reference to a FILE structure.
Float		See Real
Group	rf:Group	Field is a Group structure.
JsonClass, &JsonClass	rf:JsonClass	Field is a reference to a JSONClass object
Key	rf:key	Field is a reference to a KEY structure
Long	rf:Long	Contains a Clarion LONG which can contain a signed 32 bit number.
Numeric	rf:Numeric	Contains a number
Object	rf:Object	Contains a reference to an object.
Pointer		See Reference
PDecimal	rf:PDecimal	Field contains a PDecimal
PString	rf:PString	Field is a PString
&PString, PStringPtr	rf:PStringPtr	Field is a reference to a PString
Queue, &Queue	rf:Queue	Field contains a reference to a Queue structure.
Real	rf:Real	Contains a Clarion REAL which can contain a signed 32 bit number.
Reference	rf:Reference	Field contains a reference to an unspecified data type.
Report	rf:Report	Field contains a reference to a report structure.
Short	rf:Short	Contains a Clarion SHORT which can contain a signed 16 bit number.
Signed		See Long
String	rf:String	Field is a String
&String, StringPtr	rf:StringPtr	Field contains a reference to a string.
StringJson	rf:StringJson	String contains valid JSON text.
&StringJson	rf:StringJsonPtr	Field contains a reference to a string, which contains valid JSON text.
StringXML	rf:StringXML	String contains valid XML text.
&StringXML	rf:StringXMLPtr	Field contains a reference to a string, which contains valid XML text.
StringTheory, &StringTheory	rf:StringTheory	Field contains a reference to a StringTheory object
StringTheoryJson, &StringTheoryJson	rf:StringTheoryJson	Field contains a reference to a StringTheory object, which contains valid JSON text.
StringTheoryXML, &StringTheoryXML	rf:StringTheoryXML	Field contains a reference to a StringTheory object, which contains valid XML text.
Table, &Table		See File
ULong	rf:Ulong	Contains a Clarion ULONG which can contain an unsigned 32 bit number.
Unsigned	rf:Unsigned	See Long
UShort	rf:Ushort	Contains a Clarion USHORT which can contain an unsigned 16 bit number.
View, &View	rf:View	Field is a reference to a VIEW structure.
Window	rf:Window	Field is a reference to a WINDOW structure
Word		See UShort
xmlTreeClass, &xmlTreeClass	rf:XmlTreeClass	Field is a reference to an XMLTreeClass object

Global Extension

• Types
• Properties
• Methods
  • Add
  • Trace

Types

Properties

Methods

1.30 - 14 October 2024

• Add: Array property to FieldsQueue.
• Add: GetArray method.
• Add: Optional Index parameter to GetField and GetFieldValue.

1.29 - 4 July 2024

• Fix: Calling SetAttribute with xmlName, JsonName or Rename did not update the Rename property. ie did not behave the same as a call to .rename.

1.28 - 8 April 2024

• Fix: Having a space between attribute and value was not handled. (eg RowName (something) )
• Fix: In some situations attributes could become case sensitive.

1.27 - 7 November 2023

• Change: When calling SetAttribute, the ColumnName is passed to AdjustColumnName.

1.26 - 25 October 2023

• Fix: Parse method Typed Memos as Blobs and vice-versa.

1.25 - 10 August 2023

• Optimization: CleanFieldName method.

1.24 - 20 September 2023

• Add: Field type: rf:interface
• Internal: Performance improvements in GetFieldNumber.

1.23 - 26 July 2023

• Add: more Field Type equates (rf:file, rf:memo, rf:blob, rf:date, rf:time, rf:timestamp)
• Add: View equates (rf:ManyToOne, rf:OneToMany)
• Add: rf:iUfo interface type. (provided by Mike Duglas, originally by Oleg Rudenko)
• Add: Description and Size fields to ReflectionFieldQueueType
• Add  ParseField method
• Add: non-pointer variety of SetType method.
• Add: quick form of GetAttributeExists method.
• Add: With (GroupName) method.
• Add: SetDescription, GetDescription, SetSize, GetSize, TableFieldToColumn methods.
• Add: GetAnyType, GetAnySize methods (inspired by Jeff Slarve)
• Change: if not set, then rf:blob and rf:memo are assigned to table fields
• Internal: minor optimizations for performance
• Internal: _ParseField returns type, not 0
• Internal: Parse: If field not set, then fall back on TUFO
• Internal: Parse: If field is string then get size.
• Fix: SetAttribute would fail if passed in attribute was not left justified.
• Fix: Update attributes and lowerAttributes properties combined string when SetAttribute is called

1.22 - 26 June 2023

• Optimize: Construct call to Start
• Optimize: Only one instance of GloReflection object created in multi-dll apps

1.21 - 19 June 2023

• Optimize: Various performance optimizations.
• Fix: When parsing a memo or blob fall back on the label if the name attribute is not set.
• Fix: Column names trimmed.

1.20 - 31 May 2023

• Optimize: Various performance optimizations.

1.19 - 23 May 2023

• Fix: Using the type GROUP in the external name of a nested group could cause a GPF when DisposeGroup is called.
• Fix: After calls to DisposeQueue and DisposeGroup the pointer fields were not cleared to NULL, making reuse difficult.

1.18 - 5 April 2023

• Add: ReadStringPtrLength, ReadCStringPtrLength, ReadPStringPtrLength methods.
• Add: Parse Data types : &CstringJson, &CStringXml, CStringXML, CStringJson
• Fix: AssignCStringPtr, AssignPtringPtr created a string 1 byte too short.

1.17 - 20 February 2022

• Add: ReadStringTheoryPtrLength method.

1.16 - 27 January 2022

• Fix: Missed one.

1.15 - 26 January 2022

• Change: Maximum length of ColumnName and GroupName increased from 100 to rf:StringLen (currently 252 characters.)

1.14 - 3 October 2022

• Add: Prefix property, SetPrefix method. (property not used yet)
• Add: ClearAttribute method
• Fix: SetPrefixChars, SetReplacementChars clips passed in parameter.

1.13 - 17 September 2022

• Change: When TagCase is "CaseAny" then name is no longer lowered in Fields queue.

1.12 - 6 September 2022

• Add: rf:LastNumeric equate

1.11 - 22 August 2022

• Change: Default value for MaxPrefixLength bumped from 4 to 7 chars.
• Change: In DisposeQueue call to Free before call to Dispose.
• Add: SetRemovePrefix, SetMaxPrefixLength, SetPrefixChars, SetReplaceChars, setReplacementChars methods.

1.10 - 16 August 2022

• Add: GetField, GetFieldName, GetFieldNumber, GetFieldValue
• Add: CleanFieldName
• Add: ReadStringPtr / ReadCStringPtr / ReadPStringPtr / ReadStringTheoryPtr
• Add: SetTagCase, GetTagCase
• Add: String parameter version of SetPicture
• Add: SetReference
• Change: Parse method improved
• Change: GetAttribute method removed. Replaced with GetAttributeExists and GetAttributeValue.
• Change: Can call SetAttributes, SetAttribute, before structure is parsed.
• Fix: Prevent GPF when calling WITH, and FieldsQueue.Attributes = null
• Internal: Add Group parameter to _ParseField method
• Internal: Add _ParseAttributes method.
• Internal: Tag property changed from String the Cstring
• Internal: Start method call on construct

1.02 - 19 November 2021

• Add: ClearGroup and ClearQueue methods that don't need a GroupName parameter.
• Add: ,VIRTUAL to DESTRUCT method.

1.01 - 15 November 2021

• Changed the name of the class from ReflectionClass to ReflectClass. (ReflectionClass clashed with cpxml.clw)

1.00 - 5 November 2021

• First Release