bblfsh

README

go-client

Babelfish Go client library provides functionality to both connecting to the Babelfish server for parsing code (obtaining an UAST as a result) and for analysing UASTs with the functionality provided by libuast.

Installation

The recommended way to install go-client is:

go get -u github.com/bblfsh/go-client/v4/...

Example

CLI

Although go-client is a library, this codebase also includes an example of bblfsh-cli application at ./cmd/bblfsh-cli. When installed, it allows to parse a single file, query it with XPath and print the resulting UAST structure immediately. See $ bblfsh-cli -h for list of all available CLI options.

Code

This small example illustrates how to retrieve the UAST from a small Python script.

If you don't have a bblfsh server installed, please read the getting started guide, to learn more about how to use and deploy a bblfsh server.

Go to the quick start to discover how to run Babelfish with Docker.

package main

import (
	"context"
	"fmt"

	"github.com/bblfsh/go-client/v4"
	"github.com/bblfsh/go-client/v4/tools"

	"github.com/bblfsh/sdk/v3/uast/nodes"
	"github.com/bblfsh/sdk/v3/uast/uastyaml"
)

func main() {
    ctx := context.Background()
	client, err := bblfsh.NewClientContext(ctx, "0.0.0.0:9432")
	if err != nil {
		panic(err)
	}

	python := "import foo"
	res, _, err := client.NewParseRequest().Context(ctx).
		Language("python").Content(python).UAST()
	if err != nil {
		panic(err)
	}

	query := "//*[@role='Import']"
	it, _ := tools.Filter(res, query)
	var nodeAr nodes.Array
	for it.Next() {
		nodeAr = append(nodeAr, it.Node().(nodes.Node))
	}

	// The example below emits YAML.
	//
	// Alternative 1: encode UAST nodes to JSON.
	//   data, err := json.MarshalIndent(nodeAr, "", "  ")
	//
	// Alternative 2: encode UAST nodes to protobuf.
	//   import "github.com/bblfsh/sdk/v3/uast/nodes/nodesproto"
	//   ...
	//   for _, node := range nodesAr {
	//      err := nodesproto.WriteTo(os.Stdout, nodeAr) // check
	//      ...
	//   }
	//
	data, err := uastyaml.Marshal(nodeAr)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

produces

   { '@type': "Import",
      '@token': "import",
      '@role': [Declaration, Import, Statement],
      '@pos': { '@type': "uast:Positions",
         start: { '@type': "uast:Position",
            offset: 0,
            line: 1,
            col: 1,
         },
      },
      names: { '@type': "ImportFrom.names",
         '@role': [Identifier, Import, Incomplete, Pathname],
         'name_list': [
            { '@type': "uast:RuntimeImport",
               All: false,
               Names: ~,
               Path: { '@type': "uast:Alias",
                  '@pos': { '@type': "uast:Positions",
                  },
                  Name: { '@type': "uast:Identifier",
                     Name: "foo",
                  },
                  Node: {},
               },
               Target: ~,
            },
         ],
      },
   },
   { '@type': "ImportFrom.names",
      '@role': [Identifier, Import, Incomplete, Pathname],
      'name_list': [
         { '@type': "uast:RuntimeImport",
            All: false,
            Names: ~,
            Path: { '@type': "uast:Alias",
               '@pos': { '@type': "uast:Positions",
               },
               Name: { '@type': "uast:Identifier",
                  Name: "foo",
               },
               Node: {},
            },
            Target: ~,
         },
      ],
   },
]

iter := tools.NewIterator(res, tools.PreOrder)
for node := range tools.Iterate(iter) {
	fmt.Println(node)
}

// For XPath expressions returning a boolean/numeric/string value, you must
// use the right typed Filter function:

boolres, err := tools.FilterBool(res, "boolean(//*[@start-offset or @end-offset])")
strres, err := tools.FilterString(res, "name(//*[1])")
numres, err := tools.FilterNumber(res, "count(//*)")

Please read the Babelfish clients guide section to learn more about babelfish clients and their query language.

License

Apache License 2.0, see LICENSE

Documentation

Overview

Babelfish (https://doc.bblf.sh) Go client library provides functionality to both connect to the bblfsh daemon to parse code (obtaining an UAST as a result) and to analyse UASTs with the functionality provided by libuast.

Index

• Constants
• Variables
• type Client
  • func NewClient(endpoint string) (*Client, error)
  • func NewClientContext(ctx context.Context, endpoint string) (*Client, error)
  • func NewClientWithConnection(conn *grpc.ClientConn) (*Client, error)
  • func NewClientWithConnectionContext(ctx context.Context, conn *grpc.ClientConn) (*Client, error)
  • func (c *Client) NewParseRequest() *ParseRequest
  • func (c *Client) NewSupportedLanguagesRequest() *SupportedLanguagesRequest
  • func (c *Client) NewVersionRequest() *VersionRequest
• type DriverManifest
• type DriverManifestV2
• type Mode
  • func ParseMode(mode string) (Mode, error)
• type Node
• type ParseRequest
  • func (r *ParseRequest) Content(content string) *ParseRequest
  • func (r *ParseRequest) Context(ctx context.Context) *ParseRequest
  • func (r *ParseRequest) Do() (*protocol2.ParseResponse, error)
  • func (r *ParseRequest) Filename(filename string) *ParseRequest
  • func (r *ParseRequest) Language(language string) *ParseRequest
  • func (r *ParseRequest) Mode(mode Mode) *ParseRequest
  • func (r *ParseRequest) ReadFile(fp string) *ParseRequest
  • func (r *ParseRequest) UAST() (Node, string, error)
• type SupportedLanguagesRequest
  • func (r *SupportedLanguagesRequest) Context(ctx context.Context) *SupportedLanguagesRequest
  • func (r *SupportedLanguagesRequest) Do() ([]DriverManifest, error)
  • func (r *SupportedLanguagesRequest) DoV2() ([]DriverManifestV2, error)
• type VersionRequest
  • func (r *VersionRequest) Context(ctx context.Context) *VersionRequest
  • func (r *VersionRequest) Do() (*VersionResponse, error)
• type VersionResponse

Constants

const (
	Native    = protocol2.Mode_Native
	Annotated = protocol2.Mode_Annotated
	Semantic  = protocol2.Mode_Semantic
)

Variables

var (
	// ErrDriverFailure is returned when the driver is malfunctioning.
	ErrDriverFailure = derrors.ErrDriverFailure

	// ErrSyntax is returned when driver cannot parse the source file.
	// Can be omitted for native driver implementations.
	ErrSyntax = derrors.ErrSyntax
)

Types

type Client

type Client struct {
	*grpc.ClientConn
	// contains filtered or unexported fields
}

Client holds the public client API to interact with the bblfsh daemon.

func NewClient

func NewClient(endpoint string) (*Client, error)

NewClient is the same as NewClientContext, but assumes a default timeout for the connection.

Deprecated: use NewClientContext instead

func NewClientContext

func NewClientContext(ctx context.Context, endpoint string) (*Client, error)

NewClientContext returns a new bblfsh client given a bblfshd endpoint.

func NewClientWithConnection

func NewClientWithConnection(conn *grpc.ClientConn) (*Client, error)

NewClientWithConnection returns a new bblfsh client given a grpc connection.

func NewClientWithConnectionContext

func NewClientWithConnectionContext(ctx context.Context, conn *grpc.ClientConn) (*Client, error)

NewClientWithConnectionContext returns a new bblfsh client given a grpc connection.

func (*Client) NewParseRequest

func (c *Client) NewParseRequest() *ParseRequest

NewParseRequest is a parsing request to get the UAST.

func (*Client) NewSupportedLanguagesRequest

func (c *Client) NewSupportedLanguagesRequest() *SupportedLanguagesRequest

NewSupportedLanguagesRequest is a parsing request to get the supported languages.

func (*Client) NewVersionRequest

func (c *Client) NewVersionRequest() *VersionRequest

NewVersionRequest is a parsing request to get the version of the server.

type DriverManifest

type DriverManifest = protocol1.DriverManifest

DriverManifest contains an information about a single Babelfish driver.

Deprecated: see DoV2.

type DriverManifestV2

type DriverManifestV2 = manifest.Manifest

DriverManifestV2 contains an information about a single Babelfish driver.

type Mode

type Mode = protocol2.Mode

Mode controls the level of transformation applied to UAST.

func ParseMode

func ParseMode(mode string) (Mode, error)

Parse mode parses a UAST mode string to an enum value.

type Node

type Node = nodes.Node

Node is a generic UAST node.

type ParseRequest

type ParseRequest struct {
	// contains filtered or unexported fields
}

ParseRequest is a parsing request to get the UAST.

func (*ParseRequest) Content

func (r *ParseRequest) Content(content string) *ParseRequest

Content sets the content of the parse request. It should be the source code that wants to be parsed.

func (*ParseRequest) Context

func (r *ParseRequest) Context(ctx context.Context) *ParseRequest

Context sets a cancellation context for this request.

func (*ParseRequest) Do

func (r *ParseRequest) Do() (*protocol2.ParseResponse, error)

Do performs the actual parsing by serializing the request, sending it to bblfshd and waiting for the response.

It's the caller's responsibility to interpret errors properly.

Deprecated: use UAST() instead

func (*ParseRequest) Filename

func (r *ParseRequest) Filename(filename string) *ParseRequest

Filename sets the filename of the content.

func (*ParseRequest) Language

func (r *ParseRequest) Language(language string) *ParseRequest

Language sets the language of the given source file to parse. if missing will be guess from the filename and the content.

func (*ParseRequest) Mode

func (r *ParseRequest) Mode(mode Mode) *ParseRequest

Mode controls the level of transformation applied to UAST.

func (*ParseRequest) ReadFile

func (r *ParseRequest) ReadFile(fp string) *ParseRequest

ReadFile loads a file given a local path and sets the content and the filename of the request.

func (*ParseRequest) UAST

func (r *ParseRequest) UAST() (Node, string, error)

UAST send the request and returns decoded UAST and the language.

If a file contains syntax error, the ErrSyntax is returned and the UAST may be nil or partial in this case.

ErrDriverFailure is returned if the native driver is malfunctioning.

type SupportedLanguagesRequest

type SupportedLanguagesRequest struct {
	// contains filtered or unexported fields
}

SupportedLanguagesRequest is a request to retrieve the supported languages.

func (*SupportedLanguagesRequest) Context

func (r *SupportedLanguagesRequest) Context(ctx context.Context) *SupportedLanguagesRequest

Context sets a cancellation context for this request.

func (*SupportedLanguagesRequest) Do

func (r *SupportedLanguagesRequest) Do() ([]DriverManifest, error)

Do performs the supported languages request and return information about available drivers.

Deprecated: use DoV2 instead.

func (*SupportedLanguagesRequest) DoV2

func (r *SupportedLanguagesRequest) DoV2() ([]DriverManifestV2, error)

DoV2 performs the supported languages request and return information about available drivers.

type VersionRequest

type VersionRequest struct {
	// contains filtered or unexported fields
}

VersionRequest is a request to retrieve the version of the server.

func (*VersionRequest) Context

func (r *VersionRequest) Context(ctx context.Context) *VersionRequest

Context sets a cancellation context for this request.

func (*VersionRequest) Do

func (r *VersionRequest) Do() (*VersionResponse, error)

Do performs the actual parsing by serializing the request, sending it to bblfsd and waiting for the response.

type VersionResponse

type VersionResponse struct {
	// Version is the server version. If is a local compilation the version
	// follows the pattern dev-<short-commit>[-dirty], dirty means that was
	// compile from a repository with un-committed changes.
	Version string `json:"version"`
	// Build contains the timestamp at the time of the build.
	Build time.Time `json:"build"`
}

VersionResponse contains information about Babelfish version.