api-tools-0.8.0.1: DSL for generating API boilerplate and docs

Data.API.NormalForm

Description

This module defines a normalised representation of APIs, used for comparing them in the migrations changelog, and to analyse dependencies.

Synopsis

Normalised API types

The API type has too much extra info for us to be able to simply compare them with (==). Our strategy is to strip out ancillary information and normalise into a canonical form, and then we can use a simple (==) compare.

Our normalised API discards most of the details of each type, keeping just essential information about each type. We discard order of types and fields, so we can use just associative maps.

The normal or canonical form for a type declaration, an APINode. Equality of the normal form indicates equivalence of APIs.

We track all types.

Instances

 Source # Methods Source # MethodsshowList :: [NormTypeDecl] -> ShowS # Source # Methodsrnf :: NormTypeDecl -> () # Source # Methods

The canonical form of a record type is a map from fields to values...

...similarly a union is a map from fields to alternatives...

...and an enum is a set of values.

Converting to normal form

Compute the normal form of an API, discarding extraneous information.

Compute the normal form of a single type declaration.

Dependency analysis

Find the set of type names used in an API

Find the set of type names used in a declaration

Find the set of type names used in an type

Check if a type is declared in the API

Check if a type is used anywhere in the API

Check if the first type's transitive dependencies include the second type

Compute the transitive dependencies of a set of types

Compute the set of types that depend (transitively) on the given types

Invariant validation

Test that all the types used in the API are declared. If not, return the set of undeclared types.

Test that all the types used in a type declaration are declared in the API. If not, return the set of undeclared types.

Test that all the free type names in a type are declared in the API. If not, return the set of undeclared types.

Modifying types

Substitute types for type names in a declaration

substType :: (TypeName -> APIType) -> APIType -> APIType Source #

Substitute types for type names in a type

Rename the first type to the second throughout the API