vectorsigma

VectorSigma

VectorSigma is a tool designed to generate finite state machines (FSM) in Go from UML diagrams. It supports creating standalone applications, extending existing codebases with state machine functionality, and implementing reconciliation loops for Kubernetes (k8s) operators. This flexibility allows developers to easily integrate state machine logic into various types of applications, whether starting from scratch or enhancing existing systems.

Features

• Standalone Applications: Generate complete applications that incorporate finite state machines.
• Extend Existing Applications: Add state machine functionality to your existing applications.
• Kubernetes Integration: Support for reconciliation loops in Kubernetes operators, making it suitable for cloud-native applications.
• Incremental Updates: Perform updates that regenerate state machines without overwriting existing code. The tool intelligently adds or removes actions and guards based on changes in the UML diagram. See Incremental Updates Documentation for details.
• Simple UML Syntax: Utilize a specific UML syntax to define states, transitions, actions, and guards, making it easy to visualize and manage state machine logic.
• Markdown Support: Extract UML diagrams directly from plantuml code blocks in Markdown files, allowing you to design your state machine while documenting your project.

The state chart of VectorSigma

VectorSigma is not just a tool for generating finite state machines; it is itself a finite state machine. The following state chart illustrates the internal workings of VectorSigma, showcasing how it processes input and transitions between different states.

Writing UML

For more detailed information on the UML syntax used by VectorSigma, please refer to the VectorSigma UML Syntax Documentation. Additionally, you can view the State Chart of VectorSigma to understand the various states and transitions within the application. If you're looking to deepen your understanding of state machines and state charts in general, visit statecharts.dev for a comprehensive set of resources.

For creating UML diagrams, a good online editor to consider is planttext.com. Another option is my Markdown Preview Language Server (mpls), which supports UML and allows you to edit UML in your favorite editor while displaying the state chart in a browser. This can enhance your workflow and make it easier to visualize your state machines.

Guides and Examples

Check out these guides to help you get started:

• Getting started guide
• Building Kubernetes Operators with VectorSigma

Installation Instructions

Homebrew (macOS and Linux)

The easiest way to install and keep VectorSigma updated:

brew tap mhersson/formulas
brew install vectorsigma

To update to the latest version:

brew upgrade vectorsigma

Go Install

If you allready have Go installed on your system, you can install VectorSigma using the following command:

go install github.com/mhersson/vectorsigma@latest

If not, you can install VectorSigma by downloading the latest build from the releases page:

1. Download the appropriate tar.gz file for your operating system.

2. Extract the contents of the tar.gz file. You can do this using the following command in your terminal:

   tar xzf vectorsigma<version>_linux_amd64.tar.gz
   

   (Replace <version> with the actual version of the release.)

3. Copy the extracted binary to a directory that is in your system's PATH. For example:

   sudo cp vectorsigma /usr/local/bin/
   

Verify the installation:

After installation, you can verify that vectorsigma is installed correctly by running:

vectorsigma --version

This should display the version of the vectorsigma executable. Now, VectorSigma should be installed and ready to use.

Usage Instructions

Below are the commands and flags you can use to operate VectorSigma.

General Usage

To run VectorSigma, use the following command:

vectorsigma [command] [flags]

Available Commands

• completion: Generate the autocompletion script for your shell.
• init: Initialize a new Go module with an FSM application generated from your UML diagram.

General Flags

The Init Command

To initialize a new Go module with an FSM, use the following command:

vectorsigma init [flags]

Init Command Flags

Example Usage

To generate an FSM from a UML file, you might run:

vectorsigma --input mydiagram.uml --output internal

If your input is in a markdown file, you can run:

vectorsigma --input mydiagram.md --output internal

To initialize a new go module in the current directory (generate a default go.mod and main.go file with the FSM)

vectorsigma init --input mydiagram.uml -m github.com/yourusername/newproject

To generate the reconcile loop of an k8s operator:

vectorsigma -i myreconcileloop.uml -o internal/controller --operator --group mycompany --api-version v1 --api-kind MyCRDKind

Contributing

Contributions are welcome! I love pull requests, bug reports, and feature suggestions!