Basic auxiliary classes and modules to complement VBA

This library is a collection of modules and classes to complement VBA. The library is not intended as a one stop solution for everything VBA. It contains components for IO, VBA datastructure handling, a Collection replacement, testing and some more.

The classes in this package use a uniform, but non-standard mechanism for constructing objects. Each class is accompanied by a function in the Constructors module named ClassName_create() which returns a fully constructed instance of the repective class. These functions may take parameters. This approach provides a short object creation syntax:

List_create(1, 2, 3).elems ' 3

The mechanism does not primarily rely on the Class_Initialize() event. Each class provides one or more init() methods that may take parameters. This method is responsible for initialization of the class, but not for creating the object instance itself. The Constructors.ClassName_create() function creates a class instance, calls the init() method, forwarding all parameters it got, and returns the fully initialized instance.

Most of the modules in this library are actually implemented as Classes. The reason is to not fill up the global function namespace with all the different function names the modules provide. The functions can still be called without creating a class instance first by simply writing

ClassName.functionName()

This is made possible using a VB class attribute.

Attribute VB_PredeclaredId = True

When this attribute is attached to a class, VBA automatically creates an instance of that class on load and all method calls on the class name itself use that instance.

This library makes use of VB class and method attributes in several places. These attributes are visible in the exported text files and thus also in this repository, but the VBA editor hides them, they are simply not visible anymore. When copying methods and classes textually in the VBA editor these attributes can get lost. To edit them one has to export the module/class to a text file, edit the attributes and import the module/class again. Exporting and importing is done via right mouse button on the class/module in the Project Explorer and then choosing Export/Import File....

The Arrays module provides functions to deal with array data structures. For example creating empty arrays or sorting arrays.

Auxiliary functions to work with the collection classes of this library (List, Map, ...).

Functions to help with development of this library itself.

Simple file IO with good encoding support.

An optionally typed 0-based list implementation.

An optionally typed map implementation.

Common operations on numeric values. E.g. min(), max(), cmp()

Functions to help with using the VBScript_RegExp_55.RegExp class.

Common operations on string values. E.g. split(), join(), format()

A minimal testing framework.

Common operations on Variant values. E.g. equals(), isArray(), gist()

Excel specific functions. E.g. rowColToExcel(), sheetExists(), isWorkbookOpen()

To import all the components of this library into an Excel file one can use the DevUtils.importModules() function. To use it, just import the DevUtils class manually into the VBA project and then call DevUtils.importModules "C:\path\to\this\repo\VBA-commons-lib". This will also automatically add all the necessary references to external libraries.

Some of these classes depend on others, but to some extent they can be used independently. So when one only wants a single class or module the easiest way is to only import that module, try to build and see which modules VBA is missing.

Especially all the Test_ modules only contain tests and need not be imported.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this library except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Please report any bugs or feature requests through the web interface at https://github.com/HALTEC/VBA-commons-lib/issues.

Patrick Böker <[email protected]>, originally based on code by Mathieu Guindon that can be found on Github.