README
¶
🌳 Go Bonzai™ Common Web Requests
This web Bonzai branch contains common web requests and strives for
more command line usability than the raw net/http package or even
curl or w3m. In particular, the interface design is purposefully
simple and stateful. The high-level pkg can be used separate
from the web composable command.
Install
This command can be installed as a standalone program or composed into a Bonzai command tree.
Standalone
go install github.com/rwxrob/web/web@latest
Composed
package z
import (
Z "github.com/rwxrob/bonzai/z"
"github.com/rwxrob/web"
)
var Cmd = &Z.Cmd{
Name: `z`,
Commands: []*Z.Cmd{help.Cmd, web.Cmd},
}
Tab Completion
To activate bash completion just use the complete -C option from your
.bashrc or command line. There is no messy sourcing required. All the
completion is done by the program itself.
complete -C web web
If you don't have bash or tab completion check use the shortcut commands instead.
Embedded Documentation
All documentation (like manual pages) has been embedded into the source code of the application. See the source or run the program with help to access it.
Documentation
¶
Overview ¶
Package web provides the Bonzai command branch of the same name.
Package web provides high-level functions that are called from the Go Bonzai branch of the same name providing universal access to the core functionality.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Client = http.DefaultClient
Client provides a way to change the default HTTP client for any further package HTTP request function calls. The Client can also be set in any Req by assigning the to the field of the same name. By default, it is set to http.DefaultClient. This is particularly useful when creating mockups and other testing.
var Cmd = &Z.Cmd{ Name: `web`, Summary: `common web requests`, Version: `v0.5.0`, Copyright: `Copyright 2021 Robert S Muhlestein`, License: `Apache-2.0`, Source: `git@github.com:rwxrob/web.git`, Issues: `github.com/rwxrob/web/issues`, Commands: []*Z.Cmd{ help.Cmd, conf.Cmd, vars.Cmd, get, }, Description: ` The {{cmd .Name}} command contains common web requests and strives for more command line usability than {{pkg "net/http"}} or even {{exe "curl"}} or {{exe "w3m"}}. In particular, the interface design is purposefully simple and stateful. The high-level {{pre "pkg"}} library can be used independently from the {{cmd .Name}} composable command.`, }
main branch
var TimeOut int = 60
TimeOut is a package global timeout for any of the high-level https query functions in this package. The default value is 60 seconds.
Functions ¶
This section is empty.
Types ¶
type HTTPError ¶ added in v0.4.0
HTTPError is an error for anything other than an HTTP response in the 200-299 range including the 300 redirects (which should be handled by the Req.Submit successfully before returning). http.Response is embedded directly for details.
type Head ¶ added in v0.4.0
Head contains headers to be added to a Req. Unlike the specification, only one header of a give name is allowed. For more precision the net/http library directly should be used instead.
type Req ¶ added in v0.4.0
type Req struct {
U string // base url, optional query string
D any // data to be populated and/or overwritten
M string // all caps method (default: GET)
Q url.Values // query string to append to URL (if none already)
H Head // header map, never more than one of same
B any // body data, url.Values will x-www-form-urlencoded
C context.Context // trigger requests with context
R *http.Response // actual http.Response
}
Req is a human-friendly way to think of web requests. This design is closer a pragmatic curl requests than the canonical specification (unique headers, for example). The type and parameters of the web request and response are derived from the Req fields. The single-letter struct fields are terse but convenient. Use net/http when more precision is required.
The body (B) can be one of several types that till trigger what is submitted as data portion of the request:
url.Values - triggers x-www-form-urlencoded byte - uuencoded binary data string - plain text
Note that Req has no support for multi-part MIME. Use net/http directly if such is required.
The data (D) field can also be any of several types that trigger how the received data is handled:
[]byte - uudecoded binary string - plain text string io.Writer - keep as is json.This - unmarshaled JSON data into This any - unmarshaled JSON data
Passing the query string as url.Values automatically add a question mark (?) followed by the URL encoded values to the end of the URL which may present a problem if the URL already has a query string. Encouraging the use of url.Values for passing the query string serves as a reminder that all query strings should be URL encoded (as is often forgotten).
func (*Req) Submit ¶ added in v0.4.0
Submit synchronously sends the Req to server and populates the response from the server into D. Anything but a response in the 200s will result in an HTTPError. See Req for details on how inspection of Req will change the behavior of Submit automatically. It Req.C is nil a context.WithTimeout will be used and with the value of web.TimeOut.
type ReqSyntaxError ¶ added in v0.4.0
type ReqSyntaxError struct {
Message string
}
ReqSyntaxError is for any error involving the incorrect definition of Req fields (such as including a question mark in the URL, etc.).
func (ReqSyntaxError) Error ¶ added in v0.4.0
func (e ReqSyntaxError) Error() string
Error fulfills the error interface.
Source Files
Directories