Customer sample VSE
Customer VSE features a simple class and a collection of this class with an internal linked list. The collection, CollCust, can be iterated using a ForAll loop statement in VoltScript, and its contents can be accessed by index like a typical list.
Classes
Customer
Represents a customer's contact information and account number, as might be used by a company. This is a simple data class with no additional author code added, using only the VSID generated code. Its properties can be manipulated. These properties can be accessed directly in VoltScript, or another part of the VSE via its get and set methods.
CollCust
Represents a collection of Customer objects, using an internal linked list. The head of the list is referenced through the CustomerList property, which is generated by VSID. A pointer to the current customer has been added to implement the GetNextCustomer and GetPrevCustomer methods. Helper methods to create new Customer objects have been added to implement the OpenCustomers method to populate the collection with the contents of a text file.
This is a basic implementation that only uses the LSXBase linked list to navigate the contents of a collection. Other data structures, such as binary trees, heaps, maps, will have better performance, and should be chosen based on how the VSE will be used.
Managing a collection
OpenCustomers reads the text file located at FileName and creates Customer objects based on the lines in this file. It uses the CreateNewCustomer helper method to create the new objects. CreateNewCustomer calls the AddRef method of the newly created Customer object, which informs the VoltScript runtime that the object is being actively used and should not be garbage-collected. If AddRef is not called, the runtime will automatically delete the object when it's no longer referenced in the script code, regardless of the state of the VSE.
CloseCustomers removes all Customer objects contained by the collection without destroying the CollCust object itself. For every Customer object, DropRef is called so that the runtime is aware the VSE is no longer using the object. LSXDeleteList is then called, which unlinks and deletes all Customer objects in the collection.
Navigating a collection
The VoltScript runtime and the VSE services maintain references to all objects contained in a VSE. This includes support for linked lists of objects, such as those in a collection. Objects in a VSE can be affected by both the running VoltScript script and the VSE itself. Using the provided interfaces to interact with managed linked lists allows a VSE to manipulate objects and have the results available in the script afterwards.
CollCust provides three methods for manually walking through the collection in a script, GetFirstCustomer, GetNextCustomer, and GetPrevCustomer. These can only be used after calling OpenCustomers. The developer added member m_CurrCustomer is used to maintain the current place in the list. Refer to src/Customer/CollCust.cpp for commented source code and exact behavior.
The Customer class, like other VSE classes, extends the LSXBase class, and has GetNext and GetPrev methods that return the next or previous object in the collection, returning NULL at the end of a list or if they're not part of a collection. CollCust uses these methods to navigate the list. The LSXBase methods return pointers or references to a LSXBase, so they will need to be cast to the appropriate class.
For example, GetNextCustomer updates m_CurrCustomer to the next Customer, and returns a reference to this object. With no bounds checking or error handling, this could be done with two C++ statements:
Supporting the ForAll loop
VoltScript uses CollectionOpen, CollectionNext, and CollectionClose to iterate over the contents of a collection. These methods need to be implemented by a developer.
CollectionOpen sets arguments which are passed to later calls to CollectionNext. In CollCust, these are all set to the head of the internal linked list, CustomerList. Most of these arguments are used by the implementation, with Found terminating the loop when set to 0. CollCust only uses the Last argument to find the next object.
CollectionNext is called for every iteration of the loop, to fetch the next object in the collection. The candidate next object is found via the GetNextPtr method, and is returned to the runtime. If this object is NULL, the Found argument is set to 0, indicating that the end of the list has been reached.
CollectionClose is called when the loop terminates early to allow the VSE to perform any necessary cleanup. Nothing is required for this implementation.
Accessing an item by index
VoltScript uses the CollectionItem method to access specific indices of a collection. In VoltScript, an index can be any key, not just an integer.
CollCust implements this method by starting at the beginning of the linked list and searching every element until it finds a Customer object with the same AccNumber as the Index argument. The entire collection may need to be searched to find the desired index, resulting in poor performance with large collections.
The Found argument is set to 1 if the index was found, and is 0 otherwise.
Test script
A test script for the OpenCustomers method is provided. This script is designed to be run from the root of the VSID installation folder. The build-Customer script with the --test flag can be used to run theses tests after a build. The script uses the OpenCustomers method to populate a CollCust object, then uses a ForAll loop to iterate over each of the Customers in the collection and print some selected properties.
The test script opens the text file located at src/Customer/test/voltscript/cust.txt and parses the customer records in this file. Note that OpenCustomers method requires the data file opened to end with a blank line, and will crash if this line is not present.
On Windows, the VSE can be built and the tests run with this command:
On Linux, the command is similar:
The build-Customer.sh script may need to be set as executable before it can run.
The test script and its data are located in src/Customer/test/voltscript/.