Skip to content

Latest commit

 

History

History
262 lines (187 loc) · 12.1 KB

README.md

File metadata and controls

262 lines (187 loc) · 12.1 KB
Raw

Alchemy

Alchemy is a command line tool for modifying and transforming Matter spec documents.

It can:

  • Format your spec documents, aligning table cells, removing unneeded spacing, etc.
  • Disco-ball your spec documents, aligning them with Matter spec style guidelines
  • Generate ZAP XML files for clusters and device types
  • Generate Data Model XML files
  • Generate basic test plans for clusters
  • Compare the Matter spec to the SDK and generate a list of differences
  • Present the Matter spec as a MySQL-compatible database to run queries against
  • Print English-language explanations of Matter conformance strings

Installation

Prebuilt Binaries

Download the latest releases from the GitHub release page.

There are two builds for each architecture: plain and db. The db build includes the DB Feature below, but at the expense of a larger binary.

Build from source

Alchemy is written in pure Go, so to build from source:

  1. Install Go 1.23.1 or greater
  2. Clone the alchemy repo
  3. In the root of the alchemy repo, run go build

Commands

Common flags

Flag Default Description
--serial false Process Asciidoc files one-by-one instead of in parallel; slower
--dryrun -d false Run all logic for the command, but do not write results to disk
--patch false Write a patch file for any changes to stdout
--verbose false Display more verbose logging; best used with --serial
--attribute <name of attribute> empty string Sets an attribute for Asciidoc processing, e.g. "in-progress". This parameter can be specified multiple times for different attributes

format

Format does not alter the content of the document, but does make it easier to read the source:

  • Aligns table cells so that table delimiters correctly line up with other cells in the same column
  • Removes extraneous spacing in tables and lists
  • Normalizes properties

Examples

Flag Default Description
--wrap none The number of characters to wrap lines without disrupting Asciidoc syntax

Format a single document:

alchemy format connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Format all documents in a directory:

alchemy format connectedhomeip-spec/src/app_clusters/*.adoc

Recursively format all documents in the spec:

alchemy format connectedhomeip-spec/src/\*\*/\*.adoc

Word-wrap all documents in a directory to 120 characters:

alchemy format connectedhomeip-spec/src/app_clusters/*.adoc --wrap=120

disco

Disco-ball is more aggressive than format, and attempts to rewrite the document to the disco-ball standard:

  • Everything format does
  • Rearranges the document into disco-ball order for clusters and device-types
  • Rearranges data types into bitmap, enum, struct order
  • Promotes inline data types into the Data Types section and creates references for them
  • Normalizes all references to the ref_PascalCase format
  • Adds missing columns to tables for each type of section
  • Reorders columns in tables to match disco ball order
  • Renames headers in columns to match disco ball header names
  • Re-formats access columns into disco ball order and spacing
  • Re-formats constraint columns to be more readable (e.g. an uint with the constraint "0 to 60" -> "max 60", )
  • Fixes command directions to client (<=/=>) server format
  • Appends suffixes to sections when needed (e.g. "XyzBitmap" -> "XyzBitmap Type" or "MyField" -> "MyField Field")
  • Uppercases all hexadecimal numbers
  • Adds spaces after punctuation, when needed
  • Adds labels to anchors when missing
  • Removes extra spaces at the end of lines
  • Fixes common section naming mistakes
Flag Default Description
--linkIndexTables false Link table cells to child sections
--addMissingColumns true Add standard columns missing from tables
--reorderColumns true Rearrange table columns into disco-ball order
--renameTableHeaders true Rename table headers to disco-ball standard names
--formatAccess true Reformat access columns in disco-ball order
--promoteDataTypes true Promote inline data types to Data Types section
--reorderSections true Reorder sections in disco-ball order
--normalizeTableOptions true Remove existing table options and replace with standard disco-ball options
--fixCommandDirection true Normalize command directions
--appendSubsectionTypes true Add missing suffixes to data type sections (e.g. "Bit", "Value", "Field", etc.)
--uppercaseHex true Uppercase hex values
--addSpaceAfterPunctuation true Add missing space after punctuation
--removeExtraSpaces true Remove extraneous spaces
--normalizeFeatureNames true Normalize feature names to be compatible with downstream code generation
--disambiguateConformanceChoice false Ensure that each document only uses each conformance choice identifier once
--specRoot The root of your clone of the Matter Specification
--wrap none The number of characters to wrap lines without disrupting Asciidoc syntax

Examples

Disco-ball a single document:

alchemy disco connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Disco-ball the whole spec:

alchemy disco --specRoot=./connectedhomeip-spec

Disco-ball a single document, but update any other documents if needed (e.g. rewriting a reference):

alchemy disco --specRoot=./connectedhomeip-spec ./connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Disco-ball a single document, wrapping the text at 120 characters and linking table entries to their associated sections:

alchemy disco connectedhomeip-spec/src/app_clusters/Thermostat.adoc --wrap=120 --linkIndexTables

zap

ZAP generates zap-template XMLs from a spec, creating new XML files for provisional clusters, and amending existing XML files with changes.

Flag Default Description
--specRoot ./connectedhomeip-spec The root of your clone of the Matter Specification
--sdkRoot ./connectedhomeip The root of your clone of the Matter SDK
--overwrite false Overwrite existing XML files instead of amending them

Note

By default, existing ZAP XML files will be amended by Alchemy, leaving ordering of elements, comments and unrecognized XML attributes in place. The overwrite flag allows regenerating the XML files from scratch.

Generate ZAP files for a single cluster

alchemy zap --attribute="in-progress"  --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/ ./connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Note

Alchemy follows dependencies between clusters, so if the specified doc requires data types from other docs, it will also generate XML files for them as well. In the above case, Thermostat depends on an enumeration in OccupancySensor, so occupancy-sensing-cluster.xml will also be generated.

compare

Compare loads the spec and the ZAP template XMLs and returns their differences in JSON format.

Flag Default Description
--specRoot ./connectedhomeip-spec The root of your clone of the Matter Specification
--sdkRoot ./connectedhomeip The root of your clone of the Matter SDK
--text false Returns differences in a text format

Example

alchemy compare --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/

conformance

Conformance parses a provided conformance string and explains its meaning in plain English. It can also take a series of defined identifiers and return whether the provided conformance would consider it mandatory, optional, etc.

Examples

$ alchemy conformance "[LT | DF & CF]"
description: optional if (LT or (DF and CF))
$ alchemy conformance "AB, [CD]"
description: mandatory if AB, otherwise optional if CD
$ alchemy conformance "AB, [CD]" AB CD
description: mandatory if AB, otherwise optional if CD
conformance: Mandatory
$ alchemy conformance "AB, [CD]" EF CD
description: mandatory if AB, otherwise optional if CD
conformance: Optional
$ alchemy conformance "AB, [CD]" EF
description: mandatory if AB, otherwise optional if CD
conformance: Disallowed

dm

Data Model generates the Data Model XML files from the spec.

Flag Default Description
--specRoot ./connectedhomeip-spec The root of your clone of the Matter Specification
--sdkRoot ./connectedhomeip The root of your clone of the Matter SDK

testplan

Testplan generates basic test plan adoc files from the spec.

Flag Default Description
--specRoot ./connectedhomeip-spec The root of your clone of the Matter Specification
--testRoot ./chip-test-plans The root of your clone of the Matter test plans
--overwrite false Overwrite existing XML files instead of amending them

Note

By default, existing test plan Asciidoc files will be ignored. The overwrite flag allows regenerating the test plan Asciidoc files from scratch; this will destroy any existing tests aside from basic validation of features, attributes, etc.

alchemy-db

Alchemy-db is provided as a separate binary. It loads up a set of spec docs or ZAP templates and exposes their contents as tables in a local MySQL server you can query.

Flag Default Description
--specRoot ./connectedhomeip-spec The root of your clone of the Matter Specification
--sdkRoot ./connectedhomeip The root of your clone of the Matter SDK
--address localhost The address to bind the MySQL server to
--port 3306 The port to bind the MySQL server to
--raw false Populates the tables with the raw text of the associated entities, rather than parsing into an object model first

Examples

alchemy-db --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/