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 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 Kind
• type Name
• type Resourceness
• type Strictness

Functions

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 encoding of the type declaration.

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 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.