client

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 4, 2024 License: AGPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package client provides an HTTP client for the Stanford CoreNLP server.

See its interface Client for functionality.

See the examples for basic usage.

Example 
package main

import (
	"fmt"

	"github.com/donyori/gocorenlp/client"
	"github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
)

func main() {
	// This example is a simple procedure of annotating the string
	//  "The quick brown fox jumped over the lazy dog."
	// with Stanford CoreNLP.
	//
	// Don't run this example because there is no CoreNLP server
	// in the example environment.

	// Before calling client.AnnotateString,
	// launch a Stanford CoreNLP server listening on 127.0.0.1:9000.

	text := "The quick brown fox jumped over the lazy dog."
	annotators := "tokenize,ssplit,pos"

	// Specify the document model.
	// Depending on your CoreNLP version, use the appropriate model.
	// See package github.com/donyori/gocorenlp/model for details.
	doc := new(pb.Document)

	// Annotate the text with the specified annotators
	// and store the result in doc.
	err := client.AnnotateString(text, annotators, doc)
	if err != nil {
		panic(err) // handle error
	}

	// Work with the document.
	fmt.Println(doc.GetText())

	// [Optional]
	// Shut down the server.
	err = client.Shutdown()
	if err != nil {
		panic(err) // handle error
	}
}

Output:
Example (CacheAnnotation) 
package main

import (
	"fmt"
	"os"

	"github.com/donyori/gocorenlp/client"
)

func main() {
	// In this example, we cache the response from the Stanford CoreNLP server
	// into a local file for future use.
	//
	// Don't run this example because there is no CoreNLP server
	// in the example environment.

	// Before calling client.AnnotateStringRaw,
	// launch a Stanford CoreNLP server listening on 127.0.0.1:9000.

	text := "The quick brown fox jumped over the lazy dog."
	annotators := "tokenize,ssplit,pos"

	// Create a file to save the annotation result.
	filename := "./annotation.ann"
	f, err := os.Create(filename)
	if err != nil {
		panic(err) // handle error
	}
	defer func(f *os.File) {
		// This error handler can usually be omitted.
		if err := f.Close(); err != nil {
			_, _ = fmt.Fprintln(os.Stderr, err) // ignore error
		}
	}(f)

	// Annotate the text with the specified annotators
	// and store the result in f.
	_, err = client.AnnotateStringRaw(text, annotators, f)
	if err != nil {
		panic(err) // handle error
	}

	// Then you can use the annotation by reading it from the file.
	//
	// Note that the data written to the file is in ProtoBuf wire encoding.
	// You can decode it using the function
	// github.com/donyori/gocorenlp/model.DecodeResponseBody.

	// [Optional]
	// Shut down the server.
	err = client.Shutdown()
	if err != nil {
		panic(err) // handle error
	}
}

Output:
Example (NewClient) 
package main

import (
	"fmt"

	"github.com/donyori/gocorenlp/client"
	"github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
)

func main() {
	// Don't run this example because there is no CoreNLP server
	// in the example environment.

	// Before creating the client with default settings,
	// launch a Stanford CoreNLP server listening on 127.0.0.1:9000.

	c, err := client.New(nil) // Create a new client with default settings.
	if err != nil {
		panic(err) // handle error
	}

	text := "The quick brown fox jumped over the lazy dog."
	annotators := "tokenize,ssplit,pos"

	// Specify the document model.
	// Depending on your CoreNLP version, use the appropriate model.
	// See package github.com/donyori/gocorenlp/model for details.
	doc := new(pb.Document)

	// Annotate the text with the specified annotators
	// and store the result in doc.
	err = c.AnnotateString(text, annotators, doc)
	if err != nil {
		panic(err) // handle error
	}

	// Work with the document.
	fmt.Println(doc.GetText())

	// [Optional]
	// Shut down the server.
	err = c.ShutdownLocal()
	if err != nil {
		panic(err) // handle error
	}
}

Output:
Example (SpecifyOptions) 
package main

import (
	"fmt"
	"time"

	"github.com/donyori/gocorenlp/client"
	"github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
)

func main() {
	// Don't run this example because there is no CoreNLP server
	// in the example environment.

	// Before creating the client,
	// launch a Stanford CoreNLP server listening on the specified address.
	// The default address is 127.0.0.1:9000.

	c, err := client.New(&client.Options{
		Hostname:   "localhost", // Set the hostname here. If omitted, "127.0.0.1" is used.
		Port:       8080,        // Set the port number here. If omitted, 9000 is used.
		StatusPort: 8081,        // Set the port number of the status server here. If omitted, it is the same as Port.

		ClientTimeout: time.Second * 15,      // Set a timeout for each request here.
		Charset:       "utf-8",               // Set the charset of your text here. If omitted, "utf-8" is used.
		Annotators:    "tokenize,ssplit,pos", // Set the default annotators here.

		// Set the username and password here
		// if your server requires a basic auth.
		Username: "Alice",
		Password: "Alice's password",

		// If your server has a server ID
		// (i.e., server name, set by -server_id),
		// set it here.
		ServerID: "CoreNLPServer",
	})
	if err != nil {
		panic(err) // handle error
	}

	text := "The quick brown fox jumped over the lazy dog."

	// Specify the document model.
	// Depending on your CoreNLP version, use the appropriate model.
	// See package github.com/donyori/gocorenlp/model for details.
	doc := new(pb.Document)

	// Annotate the text with the default annotators (specified in Options above)
	// and store the result in doc.
	err = c.AnnotateString(text, "", doc)
	if err != nil {
		panic(err) // handle error
	}

	// Work with the document.
	fmt.Println(doc.GetText())

	// [Optional]
	// Shut down the server.
	err = c.ShutdownLocal()
	if err != nil {
		panic(err) // handle error
	}
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Annotate 

func Annotate(input io.Reader, annotators string, outDoc proto.Message) error

Annotate is a wrapper around Client.Annotate with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

Annotate sends an annotation request with the specified annotators to annotate the data read from the specified reader. The annotation result is represented as a CoreNLP document and stored in outDoc.

If no annotators are specified, the server's default annotators are used.

The annotators are separated by commas (,) in the string without spaces. For example: 

"tokenize,ssplit,pos,depparse"

outDoc must be a non-nil pointer to an auto-generated Document structure, for example: 

import "github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
...
outDoc := new(pb.Document)
err := Annotate(input, "tokenize,ssplit,pos", outDoc)
...

If outDoc is nil or not a pointer to Document, a runtime error occurs.

func AnnotateRaw 

func AnnotateRaw(input io.Reader, annotators string, output io.Writer) (
	written int64, err error)

AnnotateRaw is a wrapper around Client.AnnotateRaw with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

AnnotateRaw sends an annotation request with the specified annotators to annotate the data read from the specified reader. Then AnnotateRaw writes the response body to the specified writer without parsing. The user can parse it later using the function github.com/donyori/gocorenlp/model.DecodeResponseBody.

If no annotators are specified, the server's default annotators are used.

The annotators are separated by commas (,) in the string without spaces. For example: 

"tokenize,ssplit,pos,depparse"

It returns the number of bytes written and any error encountered.

func AnnotateString 

func AnnotateString(text, annotators string, outDoc proto.Message) error

AnnotateString is a wrapper around Client.AnnotateString with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

AnnotateString sends an annotation request with the specified text and annotators. The annotation result is represented as a CoreNLP document and stored in outDoc.

If no annotators are specified, the server's default annotators are used.

The annotators are separated by commas (,) in the string without spaces. For example: 

"tokenize,ssplit,pos,depparse"

outDoc must be a non-nil pointer to an auto-generated Document structure, for example: 

import "github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
...
outDoc := new(pb.Document)
err := AnnotateString("Hello world!", "tokenize,ssplit,pos", outDoc)
...

If outDoc is nil or not a pointer to Document, a runtime error occurs.

func AnnotateStringRaw 

func AnnotateStringRaw(text, annotators string, output io.Writer) (
	written int64, err error)

AnnotateStringRaw is a wrapper around Client.AnnotateStringRaw with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

AnnotateStringRaw sends an annotation request with the specified text and annotators. Then AnnotateStringRaw writes the response body to the specified writer without parsing. The user can parse it later using the function github.com/donyori/gocorenlp/model.DecodeResponseBody.

If no annotators are specified, the server's default annotators are used.

The annotators are separated by commas (,) in the string without spaces. For example: 

"tokenize,ssplit,pos,depparse"

It returns the number of bytes written and any error encountered.

func Live 

func Live() error

Live is a wrapper around Client.Live with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

Live sends a status request to the liveness endpoint (/live) and reports any error encountered to check whether the target server is online.

It returns nil if the server is online.

func Ready 

func Ready() error

Ready is a wrapper around Client.Ready with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

Ready sends a status request to the readiness endpoint (/ready) and reports any error encountered to check whether the target server is ready to accept connections.

It returns nil if the server is ready to accept connections.

func Shutdown 

func Shutdown() error

Shutdown is a wrapper around Client.ShutdownLocal with a default client. The default client connects to 127.0.0.1:9000, using all default settings (see Options for details).

Shutdown finds the shutdown key and then sends a shutdown request to stop the target server.

It returns nil if the server has been shut down successfully.

Types

type Client 

type Client interface {
	// Live sends a status request to the liveness endpoint (/live) and
	// reports any error encountered to check whether the target server
	// is online.
	//
	// It returns nil if the server is online.
	Live() error

	// Ready sends a status request to the readiness endpoint (/ready) and
	// reports any error encountered to check whether the target server
	// is ready to accept connections.
	//
	// It returns nil if the server is ready to accept connections.
	Ready() error

	// Annotate sends an annotation request with the specified annotators
	// to annotate the data read from the specified reader.
	// The annotation result is represented as
	// a CoreNLP document and stored in outDoc.
	//
	// If no annotators are specified,
	// the client's default annotators are used.
	// If the client's annotators are also not specified,
	// the server's default annotators are used.
	//
	// The annotators are separated by commas (,) in the string without spaces.
	// For example:
	//  "tokenize,ssplit,pos,depparse"
	//
	// outDoc must be a non-nil pointer to an auto-generated Document
	// structure, for example:
	//
	//  import "github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
	//  ...
	//  outDoc := new(pb.Document)
	//  err := Annotate(input, "tokenize,ssplit,pos", outDoc)
	//  ...
	//
	// If outDoc is nil or not a pointer to Document, a runtime error occurs.
	Annotate(input io.Reader, annotators string, outDoc proto.Message) error

	// AnnotateString sends an annotation request with
	// the specified text and annotators.
	// The annotation result is represented as
	// a CoreNLP document and stored in outDoc.
	//
	// If no annotators are specified,
	// the client's default annotators are used.
	// If the client's annotators are also not specified,
	// the server's default annotators are used.
	//
	// The annotators are separated by commas (,) in the string without spaces.
	// For example:
	//  "tokenize,ssplit,pos,depparse"
	//
	// outDoc must be a non-nil pointer to an auto-generated Document
	// structure, for example:
	//
	//  import "github.com/donyori/gocorenlp/model/v4.5.6-eb50467fa8e3/pb"
	//  ...
	//  outDoc := new(pb.Document)
	//  err := AnnotateString("Hello world!", "tokenize,ssplit,pos", outDoc)
	//  ...
	//
	// If outDoc is nil or not a pointer to Document, a runtime error occurs.
	AnnotateString(text, annotators string, outDoc proto.Message) error

	// AnnotateRaw sends an annotation request with the specified annotators
	// to annotate the data read from the specified reader.
	// Then AnnotateRaw writes the response body to the specified writer
	// without parsing. The user can parse it later using the function
	// github.com/donyori/gocorenlp/model.DecodeResponseBody.
	//
	// If no annotators are specified,
	// the client's default annotators are used.
	// If the client's annotators are also not specified,
	// the server's default annotators are used.
	//
	// The annotators are separated by commas (,) in the string without spaces.
	// For example:
	//  "tokenize,ssplit,pos,depparse"
	//
	// It returns the number of bytes written and any error encountered.
	AnnotateRaw(input io.Reader, annotators string, output io.Writer) (
		written int64, err error)

	// AnnotateStringRaw sends an annotation request with
	// the specified text and annotators.
	// Then AnnotateStringRaw writes the response body to
	// the specified writer without parsing.
	// The user can parse it later using the function
	// github.com/donyori/gocorenlp/model.DecodeResponseBody.
	//
	// If no annotators are specified,
	// the client's default annotators are used.
	// If the client's annotators are also not specified,
	// the server's default annotators are used.
	//
	// The annotators are separated by commas (,) in the string without spaces.
	// For example:
	//  "tokenize,ssplit,pos,depparse"
	//
	// It returns the number of bytes written and any error encountered.
	AnnotateStringRaw(text, annotators string, output io.Writer) (
		written int64, err error)

	// Shutdown sends a shutdown request with the specified key
	// to stop the target server.
	//
	// It returns nil if the server has been shut down successfully.
	Shutdown(key string) error

	// ShutdownLocal finds the shutdown key and then sends
	// a shutdown request to stop the target server.
	//
	// It works only if the target server is on the local.
	//
	// It returns nil if the server has been shut down successfully.
	ShutdownLocal() error
	// contains filtered or unexported methods
}

Client is an interface representing an HTTP client for the Stanford CoreNLP server.

func New 

func New(opt *Options) (c Client, err error)

New creates a new Client for the Stanford CoreNLP server with the specified options.

If opt is nil, it uses default options.

Before returning the client, it tests whether the target server is live. If the test fails, it reports an error and returns a nil client. Thus, make sure the server is online and set the appropriate host address in opt before calling this function.

type Options 

type Options struct {
	// Hostname is the host (without port number) of the target server.
	//
	// Default: 127.0.0.1
	Hostname string `json:"hostname,omitempty"`

	// Port is the port of the target server.
	//
	// Default: 9000
	Port uint16 `json:"port,omitempty"`

	// StatusPort is the port of the target server to run
	// the liveness and readiness server on.
	// If zero, treat it the same as the main server.
	//
	// Default: 0
	StatusPort uint16 `json:"statusPort,omitempty"`

	// ClientTimeout specifies a time limit for requests made by the client.
	// The timeout includes connection time, any redirects,
	// and reading the response body.
	//
	// Note that it does not affect the time limit of
	// the Stanford CoreNLP server to wait for an annotation
	// to finish before canceling it.
	//
	// A non-positive value means no timeout.
	//
	// Default: 0
	ClientTimeout time.Duration `json:"clientTimeout,omitempty"`

	// Username is the username sent with the request.
	// Set this along with Password if the target server requires basic auth.
	//
	// Default: "" (empty)
	Username string `json:"username,omitempty"`

	// Password is the password sent with the request.
	// Set this along with Username if the target server requires basic auth.
	//
	// Only valid when Username is not empty.
	//
	// Default: "" (empty)
	Password string `json:"password,omitempty"`

	// Charset is the character encoding of the request
	// set in the Content-Type header.
	//
	// Default: utf-8
	Charset string `json:"charset,omitempty"`

	// Annotators are the default annotators with the annotation request.
	// If no annotators are specified with the annotation request,
	// these annotators are used.
	//
	// The annotators are separated by commas (,) in the string without spaces.
	// For example:
	//  tokenize,ssplit,pos,depparse
	//
	// Default: "" (empty, no annotator is specified by default)
	Annotators string `json:"annotators,omitempty"`

	// ServerID is the value of the option -server_id used
	// when starting the target server.
	//
	// If the server is started without that option, leave it empty.
	//
	// Default: "" (empty)
	ServerID string `json:"serverID,omitempty"`
	// contains filtered or unexported fields
}

Options are the configuration for creating a new client.

func (*Options) GetHosts 

func (opt *Options) GetHosts() (main, status string)

GetHosts returns the hosts (including the hostname part and the port number part) for the main server and status server.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.