Library Synthesis

Introduction

This library provides a number of new features made possible by Synergy/DE version 9. It requires Synergy/DE version 9.3.1 or higher. It's called Synthesis for a few reasons:

The code is intended to be portable across all supported Synergy/DE platforms, which include Linux, various Unices, Windows, and OpenVMS. The Synergy/DE UI Toolkit is not required by this library, but I've taken pains to make it compatible with applications that do use the UI Toolkit.

This site documents Synthesis version 2.2.1.

Downloading

You can clone the BitBucket repository, or download sources in a tarball or ZIP file.

Author: Chip Camden
To report problems or suggestions, contact me.

Contents

  1. Introduction
  2. Contents
  3. Explanation of symbols used
  4. Building the library
  5. Primary Classes
    1. CodeCoverage - Code coverage analysis
    2. CommandLine - Command line parsing
    3. Console - Console (stdio) class
    4. ElapsedTime - Compute elapsed times
    5. File - File class
    6. Hash - Associative array
    7. json - Parse and generate JSON
    8. ls - ArrayList extensions
    9. Memo - Memoization
    10. MultiSignal - Queued events for Synergy UI Toolkit
    11. Oi - Object/integer mapping
    12. Random - Pseudorandom number generator
    13. Regex - Regular Expressions
    14. Socket - Socket as a transport
    15. Telnet - Telnet connection
    16. Transport - Serial transport mechanism
    17. Var - Type-agnostic boxing of primitives
    18. Version - Version numbers
  6. Macros and Functions
    1. Assertions - Assertions for testing
    2. fif - Functional if
    3. GotToolkit - Determine whether Toolkit is available
    4. let - Functional Let
    5. maxv, minv - Maximum/minimum values
    6. memoize - Memoize function/method results
    7. progn - evaluate multiple expressions, returning the last one
    8. swapo, swapa, swapd, swapi, swapv - swap variables
  7. Mixins
    1. Boolean - Boolean operators
    2. Comparable - Comparison operators
    3. Singleton - Singleton design pattern
  8. Utilities
    1. cover - tab-delimited code coverage report
    2. htmlcover - HTML code coverage report
  9. Change log
  10. Known issues

Explanation of symbols used

Words in italics indicate an instance of a class. The word corresponds to the class name, except where more than one instance is represented in the same statement. In that case a number (2, 3, etc.) is appended to the class name.

Words in normal typeface are to be taken literally (required punctuation, class name in a static reference, method name, etc.)

The symbol => is used to separate an expression (on the left) from its return value (on the right).

An ellipsis (...) indicates that the previous argument may be repeated any number of times. The description will indicate whether one instance is required.

Building the library

This library currently requires Synergy/DE version 9.3.1 or higher.

To set environment variables, execute one of the following:

One of the symbols set by these scripts is DBG (for debug mode). If you want to build without debug symbols, unset this environment variable.

The directory structure should be as follows:

Make files are provided for PVCS Configuration Builder (makefile.mak) and the standard Unix make(1) (Makefile). Because PVCS prefers "Makefile" over "makefile.mak", you will need to use the -f option to specify makefile.mak if you're using PVCS. If you don't have either flavor of make available, then you'll have to translate one of these files into whatever tool you use.

Build the default target in sources first, then tests and utilities. A 'make clean' will delete all target files. If you're on Windows, a 'make net' will build everything for the Synergy.NET version. In tests, you can use 'make run' or 'make runnet' to run the full test suite. Also in tests, 'make coverage' will use the htmlcover utility to generate coverage statistics for all of the tests. To combine the statistics from all tests into one report, use 'make coverall'.

In the main directory, you can do a 'make clean' to perform a 'make clean' in each of the sources, tests, and utilities directories. Likewise, a 'make all' in the main directory will do a 'make' in each of those directories.

To use the library in your application, optionally include "SYNTHESIS:synthesis.def" in your client programs (this is only really needed if you intend to use the macros and constants defined therein). Then link your program against SYNTHESIS:synthesis.elb.

Known issues