summarize

README

summarize

The summarize library is used to produce an API summary of a FIDL library. The information is extracted from the FIDL intermediate representation (IR) abstract syntax tree.

Use

Here is an example that includes the library into another go library, which is then rolled into a binary.

go_library("gopkg") {
  name = "main"
  sources = [ "main.go" ]
  deps = [
    "//tools/fidl/lib/fidlgen",
    "//tools/fidl/lib/summarize:gopkg",
  ]
}

go_binary("fidl_api_summarize") {
  gopackage = "main"
  deps = [ ":gopkg" ]
}

Then, you can refer to the functionality as:

import (
  // ...
  "go.fuchsia.dev/fuchsia/tools/fidl/lib/fidlgen"
  "go.fuchsia.dev/fuchsia/tools/fidl/lib/summarize"
)

func main() {
    // This is an incomplete code fragment: you will need to initialize in and w
    // properly.
    var (
      // in needs to be properly initialized.  The reader must yield the FIDL IR
      // you want to analyze encoded as JSON text.
      in io.Reader
      // w is where the API summary output is to be written.  Needs to be properly
      // initialized.
      w io.Writer
      // root is the root of the FIDL IR AST.
      root fidlgen.Root
    )
	root, err := fidlgen.DecodeJSONIr(in)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Could not parse FIDL IR from: %v: %v", *in, err)
		os.Exit(1)
	}
	if err := summarize.Write(root, w); err != nil {
		fmt.Fprintf(os.Stderr, "While summarizing %v into %v: %v", *in, *out, err)
		os.Exit(1)
	}
}

API usage hints

The two main functions offered by the library are summarize.Write, which will write out an API summary in text format to a writer, and summarize.Elements which yields a sequence of API elements for further analysis.

Compile

fx build tools/fidl/fidl_api_summarize

Test

Prerequisites:

• Make sure you have --with=//tools/fidl:tests in your fx set

Run the tests like so:

fx test tools/fidl/lib/summarize

Documentation

Overview

summarize is a library used to produce a FIDL API summary from the FIDL intermediate representation (IR) abstract syntax tree. Please refer to the README.md file in this repository for usage hints.

Index

• func LoadSummariesJSON(rs ...io.Reader) ([][]ElementStr, error)
• func Write(root fidlgen.Root, out io.Writer) error
• func WriteJSON(root fidlgen.Root, out io.Writer) error
• type Decl
• type Element
  • func Elements(root fidlgen.Root) []Element
• type ElementStr
  • func (e ElementStr) HasStrictness() bool
  • func (e ElementStr) IsStrict() bool
  • func (e ElementStr) Less(other ElementStr) bool
  • func (e ElementStr) String() string
• type Kind
• type Name
• type Resourceness
• type Strictness
• type Value

Functions

func LoadSummariesJSON

func LoadSummariesJSON(rs ...io.Reader) ([][]ElementStr, error)

LoadSummariesJSON loads several the API summaries in the JSON format from the given reader readers. Returns the respective summaries in the order of supplied readers, or the first encountered error.

func Write

func Write(root fidlgen.Root, out io.Writer) error

Write produces an API summary for the FIDL AST from the root into the supplied writer.

func WriteJSON

func WriteJSON(root fidlgen.Root, out io.Writer) error

WriteJSON produces an API summary for the FIDL AST from the root into the supplied writer, and formats the data as JSON.

Types

type Decl

type Decl string

Decl is the underlying type declaration. For `enum Foo : int32`, this will be `int32`.

type Element

type Element interface {
	// Stringer produces a string representation of this Element.
	fmt.Stringer
	// Member returns true if the Element is a member of something.
	Member() bool
	// Name returns the fully-qualified name of this Element.  For example,
	// "library/protocol.Method".
	Name() Name
	// Serialize converts an Element into a serializable representation.
	Serialize() ElementStr
}

Element describes a single platform surface element. Use Summarize to convert a FIDL AST into Elements.

func Elements

func Elements(root fidlgen.Root) []Element

Elements returns the API elements found in the supplied AST root in a canonical ordering.

type ElementStr

type ElementStr struct {
	Decl         `json:"declaration,omitempty"`
	Kind         `json:"kind"`
	Name         `json:"name"`
	Resourceness `json:"resourceness,omitempty"`
	Strictness   `json:"strictness,omitempty"`
	Value        `json:"value,omitempty"`
}

ElementStr is a generic stringly-typed view of an Element. The aim is to keep the structure as flat as possible, and omit fields which have no bearing to the Kind of element represented.

Keep the element ordering sorted.

func (ElementStr) HasStrictness

func (e ElementStr) HasStrictness() bool

HasStrictness returns true if this ElementStr has a notion of strictness, as not all ElementStrs do.

func (ElementStr) IsStrict

func (e ElementStr) IsStrict() bool

IsStrict returns true of this element is strict. The result makes sense only on elements that have a defined strictness.

func (ElementStr) Less

func (e ElementStr) Less(other ElementStr) bool

func (ElementStr) String

func (e ElementStr) String() string

type Kind

type Kind string

Kind is the encoding of the type, e.g. 'const'.

type Name

type Name string

Name is the fully qualified name of the element.

type Resourceness

type Resourceness string

Resourceness is whether the aggregate has resources or not.

type Strictness

type Strictness string

Strictness is whether an aggregate is strict or flexible.

type Value

type Value string

Value is a string-serialized value of the element. Since for the time being the typed value is not necessary, this is quite enough to pipe the element value through where needed.