api

Documentation

Overview

Package api defines portable Ferret-facing API metadata.

Go signatures describe how a host calls module code, but they do not always describe the FQL parameters, return values, failures, and deprecation state exposed to Ferret users. This package provides the shared API Reference v1 wire model and parses the structured documentation used to supply that Ferret-facing metadata. It also defines the version-discovery index used to locate immutable API Reference documents.

ParseDocumentation accepts normalized documentation-body text. Callers that inspect Go source are responsible for removing line or block comment markers and for attaching parser line numbers to source positions.

Index

• Constants
• func Validate(reference *Reference) error
• func ValidateIndex(index *Index) error
• type Documentation
  • func ParseDocumentation(text string) (Documentation, error)
• type DocumentationError
  • func (e *DocumentationError) Error() string
• type DocumentationErrorKind
• type Function
• type Index
  • func ParseIndex(data []byte) (*Index, error)
• type IndexVersion
• type Namespace
• type Parameter
• type Reference
  • func Parse(data []byte) (*Reference, error)
• type Return
• type Signature
• type Throw
• type Type
  • func ParseType(input string) (Type, error)
• type TypeKind
• type UnsupportedVersionError
  • func (e *UnsupportedVersionError) Error() string

Examples

• ParseDocumentation

Constants

const (
	// SchemaVersion is the supported Ferret API Reference schema version.
	SchemaVersion = 1

	// SchemaV1 is the canonical schema ID for Ferret API Reference v1.
	SchemaV1 = "https://schemas.ferretlang.org/registry/artifact/api/v1.json"

	// IndexSchemaVersion is the supported Ferret API Reference Index schema version.
	IndexSchemaVersion = 1

	// IndexSchemaV1 is the canonical schema ID for Ferret API Reference Index v1.
	IndexSchemaV1 = "https://schemas.ferretlang.org/registry/artifact/api-index/v1.json"
)

Functions

func Validate

func Validate(reference *Reference) error

Validate validates a programmatically constructed Ferret API Reference.

func ValidateIndex

func ValidateIndex(index *Index) error

ValidateIndex validates a programmatically constructed Ferret API Reference Index.

Types

type Documentation

type Documentation struct {
	// Description contains ordinary prose with structured annotation lines removed.
	Description string
	// Parameters contains authored parameters in declaration order.
	Parameters []Parameter
	// Return contains the single authored return value when present.
	Return *Return
	// Throws contains every authored failure in declaration order.
	Throws []Throw
	// Deprecated contains the authored structured deprecation message.
	Deprecated string
}

Documentation contains the Ferret-facing metadata parsed from one declaration comment.

func ParseDocumentation

func ParseDocumentation(text string) (Documentation, error)

ParseDocumentation parses normalized documentation-body text into ordinary prose and structured Ferret-facing metadata. Supported annotations must begin at the first character of their line. The returned value is fully validated.

Example

package main

import (
	"fmt"

	"github.com/MontFerret/specs/pkg/api"
)

func main() {
	text := `Decode decodes XML content into a normalized document object.

@param data {String|Binary} XML content.
@return {Object} Normalized XML document.`

	documentation, err := api.ParseDocumentation(text)
	if err != nil {
		panic(err)
	}

	fmt.Println(documentation.Description)
	parameterType := documentation.Parameters[0].Type
	fmt.Println(documentation.Parameters[0].Name, parameterType.Types[0].Name, parameterType.Types[1].Name)
	fmt.Println(documentation.Return.Type.Name)
}

Output:
Decode decodes XML content into a normalized document object.
data String Binary
Object

type DocumentationError

type DocumentationError struct {
	// Kind identifies the stable documentation failure category.
	Kind DocumentationErrorKind
	// Line is one-based within the normalized documentation body.
	Line int
	// Annotation is the original malformed or conflicting annotation line.
	Annotation string
	// Detail describes the expected grammar or semantic conflict.
	Detail string
}

DocumentationError reports one invalid structured annotation. Line is one-based within the normalized documentation body.

func (*DocumentationError) Error

func (e *DocumentationError) Error() string

type DocumentationErrorKind

type DocumentationErrorKind string

DocumentationErrorKind identifies a stable structured-documentation failure category.

const (
	// DocumentationErrorMalformedAnnotation identifies invalid supported-tag grammar.
	DocumentationErrorMalformedAnnotation DocumentationErrorKind = "malformed-annotation"
	// DocumentationErrorDuplicateParameter identifies a repeated parameter name.
	DocumentationErrorDuplicateParameter DocumentationErrorKind = "duplicate-parameter"
	// DocumentationErrorMultipleReturns identifies more than one @return annotation.
	DocumentationErrorMultipleReturns DocumentationErrorKind = "multiple-returns"
	// DocumentationErrorMultipleDeprecations identifies more than one @deprecated annotation.
	DocumentationErrorMultipleDeprecations DocumentationErrorKind = "multiple-deprecations"
)

type Function

type Function struct {
	// Name is the case-sensitive Ferret function name.
	Name string `json:"name"`
	// Signatures contains every distinct fixed or variadic signature.
	Signatures []Signature `json:"signatures"`
}

Function contains every registered overload for one Ferret function name.

type Index

type Index struct {
	// SchemaVersion identifies the API Reference Index wire contract.
	SchemaVersion int `json:"schemaVersion"`
	// Latest is the greatest stable version, omitted when only prereleases exist.
	Latest string `json:"latest,omitempty"`
	// Versions contains every published API Reference in descending semantic-version order.
	Versions []IndexVersion `json:"versions"`
}

Index discovers immutable API Reference artifacts by version.

func ParseIndex

func ParseIndex(data []byte) (*Index, error)

ParseIndex strictly decodes and validates one Ferret API Reference Index document.

type IndexVersion

type IndexVersion struct {
	// Version is the immutable API Reference version.
	Version string `json:"version"`
	// Href is the URI reference consumers follow to load the API Reference.
	Href string `json:"href"`
}

IndexVersion links one semantic version to its authoritative API Reference location.

type Namespace

type Namespace struct {
	// Name is the case-sensitive Ferret namespace or an empty global namespace.
	Name string `json:"name"`
	// Functions contains the registered functions in deterministic order.
	Functions []Function `json:"functions"`
}

Namespace contains the functions registered in one Ferret namespace. An empty name identifies the global namespace.

type Parameter

type Parameter struct {
	// Name is the Ferret-facing parameter name.
	Name string `json:"name"`
	// Type describes the documented Ferret semantic type. Nil means the
	// parameter type was not documented.
	Type *Type `json:"type,omitempty"`
	// Description explains the parameter's Ferret-facing meaning.
	Description string `json:"description,omitempty"`
}

Parameter describes one Ferret-facing function parameter.

type Reference

type Reference struct {
	// SchemaVersion identifies the API Reference wire contract.
	SchemaVersion int `json:"schemaVersion"`
	// ID is the canonical lowercase owner/module coordinate.
	ID string `json:"id"`
	// Version is the immutable module version described by this reference.
	Version string `json:"version"`
	// Namespaces contains the registered Ferret namespaces in deterministic order.
	Namespaces []Namespace `json:"namespaces"`
}

Reference contains the statically derived Ferret-facing API for one module version.

func Parse

func Parse(data []byte) (*Reference, error)

Parse strictly decodes and validates one Ferret API Reference document.

type Return

type Return struct {
	// Type describes the documented Ferret semantic result type.
	Type *Type `json:"type"`
	// Description explains the result's Ferret-facing meaning.
	Description string `json:"description"`
}

Return describes a documented Ferret-facing function result.

type Signature

type Signature struct {
	// Parameters contains the Ferret-facing parameters in call order.
	Parameters []Parameter `json:"parameters"`
	// Variadic reports whether registration exposes a variadic signature.
	Variadic bool `json:"variadic,omitempty"`
	// Description contains ordinary declaration prose without structured annotations.
	Description string `json:"description,omitempty"`
	// Return describes the Ferret-facing result when one is documented.
	Return *Return `json:"return,omitempty"`
	// Throws contains documented Ferret-visible failures in source order.
	Throws []Throw `json:"throws,omitempty"`
	// Deprecated contains the structured deprecation message when present.
	Deprecated string `json:"deprecated,omitempty"`
}

Signature describes one fixed-arity or variadic Ferret function definition.

type Throw

type Throw struct {
	// Error is an opaque Ferret error expression preserved as authored.
	Error string `json:"error"`
	// Description explains when the failure is visible to a Ferret caller.
	Description string `json:"description"`
}

Throw describes one documented Ferret-visible function failure.

type Type

type Type struct {
	// Kind selects the named, union, or list variant.
	Kind TypeKind `json:"kind"`
	// Name contains the open semantic name for a named type.
	Name string `json:"name,omitempty"`
	// Types contains the ordered members of a union type.
	Types []Type `json:"types,omitempty"`
	// Element contains the recursive element of a list type.
	Element *Type `json:"element,omitempty"`
}

Type describes a recursive Ferret-facing semantic type. Exactly one variant field must be present for the selected Kind.

func ParseType

func ParseType(input string) (Type, error)

ParseType parses one documentation type expression into its normalized recursive representation.

type TypeKind

type TypeKind string

TypeKind identifies one recursive Ferret API type variant.

const (
	// TypeKindNamed identifies an open named Ferret semantic type.
	TypeKindNamed TypeKind = "named"
	// TypeKindUnion identifies an ordered choice of semantic types.
	TypeKindUnion TypeKind = "union"
	// TypeKindList identifies a homogeneous list of one semantic element type.
	TypeKindList TypeKind = "list"
)

type UnsupportedVersionError

type UnsupportedVersionError struct {
	// Version is the unsupported positive schema version.
	Version int
}

UnsupportedVersionError reports a positive API Reference schema version other than v1.

func (*UnsupportedVersionError) Error

func (e *UnsupportedVersionError) Error() string