vppapi

Documentation

Overview

Package vppapi parses VPP API files without any additional processing.

Index

• Constants
• func FindFiles(dir string) (files []string, err error)
• func FindFilesRecursive(dir string, deep int) (files []string, err error)
• func GetVPPVersionInstalled() (string, error)
• func GetVPPVersionRepo(repoDir string) (string, error)
• func ResolveApiDir(dir string) string
• func ResolveVPPVersion(apidir string) string
• type AliasType
• type Counter
• type CounterPaths
• type Element
• type EnumEntry
• type EnumType
• type Field
• type File
  • func ParseDefault() ([]File, error)
  • func ParseDir(apiDir string) ([]File, error)
  • func ParseFile(apiFile string) (*File, error)
  • func ParseRaw(content []byte) (file *File, err error)
• type InputFormat
• type InputRef
  • func ParseInputRef(input string) (*InputRef, error)
  • func (ref *InputRef) Retrieve() (*VppInput, error)
• type Message
• type RPC
• type Schema
• type Service
• type StructType
• type UnionType
• type VppInput
  • func ResolveVppInput(input string) (*VppInput, error)

Constants

const (
	OptionFormat = "format"

	OptionGitBranch = "branch"
	OptionGitTag    = "tag"
	OptionGitRef    = "ref"
	OptionGitDepth  = "depth"
	OptionGitSubdir = "subdir"

	OptionArchiveCompression = "compression"
	OptionArchiveSubdir      = "subdir"
	OptionArchiveStrip       = "strip"
)

const (
	VPPVersionEnvVar = "VPP_VERSION"
	VPPVersionFile   = "VPP_VERSION"
	VPPDirEnvVar     = "VPP_DIR"
)

const (
	// DefaultDir is default location of API files.
	DefaultDir = "/usr/share/vpp/api"

	// APIFileExtension is a VPP API file extension suffix.
	APIFileExtension = ".api.json"
)

const (
	OptFileVersion = "version"
)

Functions

func FindFiles

func FindFiles(dir string) (files []string, err error)

FindFiles searches for API files in specified directory or in a subdirectory that is at most 1-level deeper than dir. This effectively finds all API files under core & plugins directories inside API directory. The returned list of files will contain paths relative to dir.

func FindFilesRecursive

func FindFilesRecursive(dir string, deep int) (files []string, err error)

FindFilesRecursive recursively searches for API files inside specified directory or a subdirectory that is not nested more than deep. The returned list of files will contain paths relative to dir.

func GetVPPVersionInstalled

func GetVPPVersionInstalled() (string, error)

GetVPPVersionInstalled retrieves VPP version of installed package using dpkg-query.

func GetVPPVersionRepo

func GetVPPVersionRepo(repoDir string) (string, error)

GetVPPVersionRepo retrieves VPP version using script in repo directory.

func ResolveApiDir

func ResolveApiDir(dir string) string

ResolveApiDir checks if parameter dir is a path to directory of local VPP repository and returns path to directory with VPP API JSON files under build-root. It will execute `make json-api-files` in case the folder with VPP API JSON files does not exist yet.

func ResolveVPPVersion

func ResolveVPPVersion(apidir string) string

ResolveVPPVersion resolves version of the VPP for target directory.

Version resolved here can be overriden by setting VPP_VERSION env var.

Types

type AliasType

type AliasType struct {
	Name   string
	Type   string
	Length int `json:",omitempty"`
}

type Counter

type Counter struct {
	Name     string
	Elements []Element `json:",omitempty"`
}

type CounterPaths

type CounterPaths struct {
	Name  string
	Paths []string `json:",omitempty"`
}

type Element

type Element struct {
	Name        string
	Severity    string
	Type        string
	Units       string
	Description string
}

type EnumEntry

type EnumEntry struct {
	Name  string
	Value uint32
}

type EnumType

type EnumType struct {
	Name    string
	Type    string
	Entries []EnumEntry
}

type Field

type Field struct {
	Name     string
	Type     string
	Length   int                    `json:",omitempty"`
	Array    bool                   `json:",omitempty"`
	SizeFrom string                 `json:",omitempty"`
	Meta     map[string]interface{} `json:",omitempty"`
}

type File

type File struct {
	Name string // Name is the name of this API file (without any extension).
	Path string // Path is the location of thi API file relative to API directory.
	CRC  string // CRC is a checksum for this API file.

	// Options is a map of string key-value pairs that provides additional options for this file.
	Options map[string]string `json:",omitempty"`
	// Imports is a list of strings representing the names of API files that are imported by this file.
	Imports []string `json:",omitempty"`

	AliasTypes    []AliasType  `json:",omitempty"`
	EnumTypes     []EnumType   `json:",omitempty"`
	EnumflagTypes []EnumType   `json:",omitempty"`
	StructTypes   []StructType `json:",omitempty"`
	UnionTypes    []UnionType  `json:",omitempty"`

	// Messages is a list of Message objects representing messages used in the API.
	Messages []Message `json:",omitempty"`
	// Service is an object representing the RPC services used in the API.
	// In case there is not any services defined for this File, the Service is nil.
	Service *Service `json:",omitempty"`

	Counters []Counter      `json:",omitempty"`
	Paths    []CounterPaths `json:",omitempty"`
}

File is a single API file and its contents.

func ParseDefault

func ParseDefault() ([]File, error)

ParseDefault parses API files in the directory DefaultDir, which is a default location of the API files for VPP installed on the host system, and returns list of File or an error if any occurs.

func ParseDir

func ParseDir(apiDir string) ([]File, error)

ParseDir searches for API files in apiDir, parses them and returns list of File or an error if any occurs during searching or parsing. The returned files will have Path field set to a path relative to apiDir.

API files must have suffix `.api.json` and must be formatted as JSON.

func ParseFile

func ParseFile(apiFile string) (*File, error)

ParseFile parses API file and returns File or an error if any error occurs during parsing. The retrurned file will have Path field set to apiFile.

func ParseRaw

func ParseRaw(content []byte) (file *File, err error)

ParseRaw parses raw API file content and returns File or an error if any error occurs during parsing.

type InputFormat

type InputFormat string

const (
	FormatDir InputFormat = "dir"
	FormatGit InputFormat = "git"
	FormatTar InputFormat = "tar"
	FormatZip InputFormat = "zip"
)

type InputRef

type InputRef struct {
	Path    string
	Format  InputFormat
	Options map[string]string
}

InputRef is used to specify reference to VPP API input.

func ParseInputRef

func ParseInputRef(input string) (*InputRef, error)

func (*InputRef) Retrieve

func (ref *InputRef) Retrieve() (*VppInput, error)

type Message

type Message struct {
	Name    string
	Fields  []Field
	CRC     string
	Options map[string]string `json:",omitempty"`
	Comment string            `json:",omitempty"`
}

type RPC

type RPC struct {
	Request   string
	Reply     string
	Stream    bool     `json:",omitempty"`
	StreamMsg string   `json:",omitempty"`
	Events    []string `json:",omitempty"`
}

type Schema

type Schema struct {
	// Files is a list of File objects that are part of this scheme.
	Files []File
	// Version is a VPP version of this schema.
	Version string
}

Schema represents a collection of API files for a specific VPP version.

type Service

type Service struct {
	RPCs []RPC `json:",omitempty"`
}

type StructType

type StructType struct {
	Name   string
	Fields []Field
}

type UnionType

type UnionType struct {
	Name   string
	Fields []Field
}

type VppInput

type VppInput struct {
	ApiDirectory string
	Schema       Schema
}

VppInput defines VPP API input source.

func ResolveVppInput

func ResolveVppInput(input string) (*VppInput, error)

ResolveVppInput parses an input string and returns VppInput or an error if a problem occurs durig parsing. The input string consists of path, which can be followed by '#' and one or more options separated by comma. The actual format can be specified explicitely by an option 'format', if that is not the case then the format will be detected from path automatically if possible.

- `path` - `path#option1=val,option2=val`

Available formats:

* Directory: `dir`

• absolute: `/usr/share/vpp/api`
• relative: `path/to/apidir`

* Git repository: `git`

• local repository: `.git`
• remote repository: `https://github.com/FDio/vpp.git`

* Tarball/Zip Archive (`tar`/`zip`)

• local archive: `api.tar.gz`
• remote archive: `https://example.com/api.tar.gz`
• standard input: `-`

Format options:

* Git repository

• `branch`: name of branch
• `tag`: specific git tag
• `ref`: git reference
• `depth`: git depth
• `subdir`: subdirectory to use as base directory

* Tarball/ZIP Archive

• `compression`: compression to use (`gzip`)
• `subdir`: subdirectory to use as base directory
• 'strip': strip first N directories, applied before `subdir`

Returns VppInput on success.