Documentation
¶
Overview ¶
Package syntax parses .hurl/.sonde files into a lossless AST, prints it back byte for byte, formats it canonically and renders diagnostics.
The parser is recursive descent with backtracking: a recoverable error lets the caller try another alternative, a non-recoverable one stops parsing.
Index ¶
- Constants
- func Format(f *File) []byte
- func IsMethodLine(s string) bool
- func ParseAll(name string, src []byte, d Dialect, limit int) (f *File, errs []*Error)
- func Print(f *File) []byte
- func SourceLines(s string) []string
- func ValidCloseCode(code int) bool
- type Assert
- type Base64
- type BasicAuth
- type Body
- type BodySpec
- type Boolean
- type Bytes
- type Capture
- type CertificateAttribute
- type Comment
- type CookieAttribute
- type CookiePath
- type Dialect
- type Duration
- type Entry
- type EntrySpec
- type Error
- type ErrorKind
- type Expr
- type ExprKind
- type Field
- type File
- type FileRef
- type FilenameParam
- type FilenameValue
- type Filter
- type FilterItem
- type FilterKind
- type GraphQLVariables
- type Hex
- type Identifier
- type JSONList
- type JSONListElement
- type JSONNumber
- type JSONObject
- type JSONObjectElement
- type JSONValue
- type KeyValue
- type LineTerminator
- type Member
- type Members
- type MessageStep
- type Method
- type MultilineKind
- type MultilineString
- type MultipartField
- type MultipartFile
- type MultipartParam
- type Node
- type Null
- type Number
- type NumberKind
- type Option
- type OptionField
- func BoolOption(name string, v bool) OptionField
- func DurationOption(name string, d time.Duration) OptionField
- func FilenameOption(name string, path Text) OptionField
- func IntOption(name string, n int64) OptionField
- func StringOption(name string, v Text) OptionField
- func VariableOption(name string, v Text) OptionField
- type Placeholder
- type Pos
- type Predicate
- type PredicateFunc
- type PredicateKind
- type PredicateValue
- type Query
- type QueryKind
- type Regex
- type Request
- type Response
- type ResponseSpec
- type Section
- type SectionKind
- type Span
- type Status
- type StepKind
- type StreamField
- type Template
- type TemplateElement
- type TemplateString
- type Text
- type TextElem
- type VariableDefinition
- type Version
- type Whitespace
- type XML
Constants ¶
const MaxFileSize = 64 << 20
MaxFileSize is the largest source Parse accepts.
Variables ¶
This section is empty.
Functions ¶
func Format ¶
Format renders f canonically. Only horizontal whitespace and line endings change; blank lines, comments, order and body content are kept:
- no indentation; one space after `:` and between assert/capture parts;
- trailing whitespace removed, blank lines emptied;
- LF line endings outside bodies and a final newline.
func IsMethodLine ¶
IsMethodLine reports whether s starts, after spaces and tabs, with an uppercase method name other than HTTP followed by a space or tab: the first line of a request.
func ParseAll ¶
ParseAll parses src like Parse but does not stop at the first error: after a failure it resumes at the next line that starts with an HTTP method, so every broken entry gets its own error. The returned File holds the entries that parsed (LineTerminators only when the file parsed to its end); errs holds at most limit errors, in source order. The first error is always the one Parse would return.
func Print ¶
Print renders f back to source; for a parsed file the output is identical to the input. Literal nodes print their Source text (TemplateString, Number, JSONNumber, Regex, Base64, Hex), so code that builds or edits such nodes must set Source; a CookiePath prints its parts when Source is empty.
func SourceLines ¶
SourceLines splits source text into lines: "\n" separators, a trailing "\r" removed, no final empty line.
func ValidCloseCode ¶ added in v1.2.0
ValidCloseCode reports whether a WebSocket close frame may carry code (RFC 6455 §7.4): 1000-4999 except the codes reserved for local use.
Types ¶
type Assert ¶
type Assert struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Query *Query
Filters []*FilterItem
Space1 Whitespace
Predicate *Predicate
Span Span // from the query to the end of the predicate
LineTerminator0 *LineTerminator
}
Assert is `query filters* predicate`.
type Base64 ¶
type Base64 struct {
Space0 Whitespace
Value []byte
Source string
Space1 Whitespace
}
Base64 is `base64, ... ;`.
type BasicAuth ¶
type BasicAuth struct{ User, Password Text }
BasicAuth is the one user:password pair of BasicAuth.
type Body ¶
type Body struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Value Bytes
Span Span // the body value
LineTerminator0 *LineTerminator
}
Body is a request or response body.
type BodySpec ¶
type BodySpec struct {
// contains filtered or unexported fields
}
BodySpec is a request or response body, already rendered to its literal source form.
func GraphQLBody ¶
GraphQLBody builds a ```graphql``` body from query, with a trailing `variables` object when variables is non-nil (Members or map[string]any, nested as JSONBody accepts). When query can't be written in that form, it falls back to the equivalent JSON body {"query": ..., "variables": ...}, which is what a GraphQL body sends.
func JSONBody ¶
JSONBody builds a JSON body from v, which must be built from nil, bool, float64, json.Number, string, Text (a string with placeholders), Members or map[string]any (sorted by key) and []any, nested as needed.
func RawTextBody ¶
RawTextBody builds a multiline body from text tagged with lang (e.g. "graphql"); lang == "" selects the untemplated ```raw``` form, which accepts any text but never expands {{ }} placeholders. It falls back to a oneline backtick string when text contains the closing fence, or (for a templated lang) could be misread as a {{ }} placeholder or, for graphql, a trailing `variables` block; it falls back to a base64 body when text is not valid UTF-8.
func TextBody ¶
TextBody builds a templated body from t, whose placeholders stay live: a ```lang``` multiline string (lang is "", "json", "xml" or "graphql"), or a oneline backtick string when the literal parts could be misread there. Text that is not valid UTF-8 and holds no placeholder becomes a base64 body.
type Bytes ¶
type Bytes interface {
Node
// contains filtered or unexported methods
}
Bytes is a body value: a JSONValue, *XML, *MultilineString, *Template (backtick), *Base64, *Hex or *FileRef.
type Capture ¶
type Capture struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Name *Template
Space1 Whitespace
Space2 Whitespace
Query *Query
Filters []*FilterItem
Space3 Whitespace // before `redact`, empty otherwise
Redact bool
Span Span // from the name to the last filter or `redact`
LineTerminator0 *LineTerminator
}
Capture is `name: query filters* redact?`.
type CertificateAttribute ¶
type CertificateAttribute struct {
Name string
}
CertificateAttribute is the quoted field of a certificate query, e.g. "Subject" (stored without quotes).
type CookieAttribute ¶
type CookieAttribute struct {
Space0 Whitespace
Name string // as written; matched case-insensitively
Space1 Whitespace
}
CookieAttribute is `[ Name ]` in a cookie path.
type CookiePath ¶
type CookiePath struct {
Source string
Name *Template
Attribute *CookieAttribute
}
CookiePath is a cookie query argument: `"name[Attribute]"`. Source is the text between the quotes; clear it after editing Name or Attribute.
type Dialect ¶
type Dialect int
Dialect selects the accepted language: .hurl files are strictly the standard grammar; .sonde files add the Sonde-prefixed extensions of docs/decisions/0004-streaming-protocols.md ([SondeMessages], sonde-stream-* options, the sondeStream query).
func DialectFor ¶
DialectFor picks the dialect from a file name's extension.
type EntrySpec ¶
type EntrySpec struct {
// Comments are written as one or more `#` lines above the request.
Comments []string
Method string
URL Text
Headers []Field
Query []Field
Form []Field
Cookies []Field
Multipart []MultipartField
BasicAuth *BasicAuth
Options []OptionField
Body *BodySpec
Response *ResponseSpec
}
EntrySpec describes one request, and optionally its expected response, to render with BuildFile.
type Error ¶
Error is a parse error at a single position; parsing stops at the first one.
func (*Error) Description ¶
Description is the short title, e.g. "Parsing literal".
type ErrorKind ¶
type ErrorKind int
ErrorKind classifies a parse error.
const ( ErrDuplicateSection ErrorKind = iota ErrEscapeChar ErrExpecting // Arg: expected literal ErrFileContentType ErrFilename ErrGraphQLVariables ErrHexDigit ErrInvalidCookieAttribute ErrInvalidDurationUnit // Arg: unit ErrInvalidOption // Arg: option name ErrJSONTrailingComma ErrJSONExpectingElement ErrJSONEmptyElement ErrJSONPathExpr ErrMethod // Arg: method name ErrMultiline ErrMultilineLanguageHint // Arg: hint ErrOddNumberOfHexDigits ErrPredicate ErrPredicateValue ErrRegexExpr // Arg: regex error ErrRequestSection ErrRequestSectionName // Arg: section name ErrResponseSection ErrResponseSectionName // Arg: section name ErrSpace ErrStatus ErrTemplateVariable ErrUnicode ErrURLIllegalCharacter // Arg: character ErrURLInvalidStart ErrVariable // Arg: message ErrVersion ErrXPathExpr ErrXML // Input guards. ErrInvalidUTF8 ErrFileTooLarge ErrNestingTooDeep // Sonde extensions. ErrSondeOnly // Arg: the construct, e.g. "section `[SondeMessages]`" ErrMessageStep // Arg: step name ErrStreamField // Arg: field name ErrMessageValue ErrGrpcField // Arg: field name ErrGrpcKey // Arg: key )
Parse error kinds. Kinds with a parameter carry it in Error.Arg.
type Field ¶
type Field struct{ Key, Value Text }
Field is a `key: value` line: a header, a query/form/cookie param, or the BasicAuth user/password pair.
type File ¶
type File struct {
// BOM is set when the source starts with a UTF-8 byte order mark, which
// is skipped by the parser and kept by the printer.
BOM bool
Entries []*Entry
// LineTerminators are the blank and comment lines after the last entry.
LineTerminators []*LineTerminator
}
File is a parsed request file.
type FileRef ¶
type FileRef struct {
Space0 Whitespace
Filename *Template
Space1 Whitespace
}
FileRef is `file, name ;`.
type FilenameParam ¶
type FilenameParam struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Key *Template
Space1 Whitespace
Space2 Whitespace
Value *FilenameValue
LineTerminator0 *LineTerminator
}
FilenameParam is `key: file,name; content-type`.
type FilenameValue ¶
type FilenameValue struct {
Space0 Whitespace
Filename *Template
Space1 Whitespace
Space2 Whitespace
ContentType *Template
}
FilenameValue is `file,` space0 filename space1 `;` space2 content-type?.
type Filter ¶
type Filter struct {
Span Span
Kind FilterKind
Space0 Whitespace
Arg Node
Space1 Whitespace
Arg2 Node
}
Filter transforms a query result. Arguments are preceded by Space0/Space1.
type FilterItem ¶
type FilterItem struct {
Space Whitespace
Filter *Filter
}
FilterItem is a filter with the whitespace before it.
type FilterKind ¶
type FilterKind int
FilterKind identifies a filter; String returns its keyword.
const ( FilterBase64Decode FilterKind = iota FilterBase64Encode FilterBase64URLSafeDecode FilterBase64URLSafeEncode FilterCharsetDecode // Arg: *Template FilterCount FilterDaysAfterNow FilterDaysBeforeNow FilterDecode // Arg: *Template (deprecated alias of charsetDecode) FilterFirst FilterFormat // Arg: *Template (deprecated alias of dateFormat) FilterDateFormat // Arg: *Template FilterHTMLEscape FilterHTMLUnescape FilterJSONPath // Arg: *Template FilterLast FilterLocation FilterNth // Arg: *Number or *Placeholder FilterRegex // Arg: *Template or *Regex FilterReplace // Arg, Arg2: *Template FilterReplaceRegex // Arg: *Template or *Regex; Arg2: *Template FilterSplit // Arg: *Template FilterToDate // Arg: *Template FilterToFloat FilterToHex FilterToInt FilterToString FilterURLDecode FilterURLEncode FilterURLQueryParam // Arg: *Template FilterUTF8Decode FilterUTF8Encode FilterXPath // Arg: *Template )
Filter kinds.
func (FilterKind) String ¶
func (k FilterKind) String() string
type GraphQLVariables ¶
type GraphQLVariables struct {
Space Whitespace
Value *JSONObject
Whitespace Whitespace
}
GraphQLVariables is the `variables {...}` block closing a graphql string.
type Hex ¶
type Hex struct {
Space0 Whitespace
Value []byte
Source string
Space1 Whitespace
}
Hex is `hex, ... ;`.
type Identifier ¶
type Identifier struct {
Value string
}
Identifier is a bare keyword value, e.g. the verbosity level.
type JSONList ¶
type JSONList struct {
Space0 string
Elements []*JSONListElement
}
JSONList is `[ elements ]`; Space0 follows `[` when the list is empty.
type JSONListElement ¶
JSONListElement is a list item with surrounding whitespace.
type JSONObject ¶
type JSONObject struct {
Space0 string
Elements []*JSONObjectElement
}
JSONObject is `{ members }`; Space0 follows `{` when the object is empty.
type JSONObjectElement ¶
type JSONObjectElement struct {
Space0 string
Name *Template
Space1 string
Space2 string
Value JSONValue
Space3 string
}
JSONObjectElement is `"name": value` with surrounding whitespace.
type JSONValue ¶
type JSONValue interface {
Node
// contains filtered or unexported methods
}
JSONValue is *Null, *Boolean, *JSONNumber, *Template (string, delimiter '"'), *Placeholder, *JSONList or *JSONObject.
type KeyValue ¶
type KeyValue struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Key *Template
Space1 Whitespace
Space2 Whitespace
Value *Template
LineTerminator0 *LineTerminator
}
KeyValue is `key: value` (headers, params, cookies, basic auth).
type LineTerminator ¶
type LineTerminator struct {
Space0 Whitespace
Comment *Comment
Newline Whitespace
}
LineTerminator is `sp* comment? newline?`; the newline is empty at EOF.
type Members ¶
type Members []Member
Members is an ordered list of JSON object members, for JSONBody's v.
type MessageStep ¶ added in v1.2.0
type MessageStep struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Kind StepKind
Space1 Whitespace
Colon bool
Space2 Whitespace
// Value is a Bytes for send, a *Number or *Placeholder for receive and
// close, nil without a value.
Value Node
Span Span // from the step keyword to the end of its value
LineTerminator0 *LineTerminator
}
MessageStep is one step of a [SondeMessages] section: `send: body`, `receive`, `receive: N`, `close` or `close: CODE`. Colon is false for a bare `receive` or `close`, whose Space1, Space2 and Value are then empty.
type MultilineKind ¶
type MultilineKind int
MultilineKind is the language of a multiline string.
const ( MultilineText MultilineKind = iota MultilineJSON MultilineXML MultilineRaw MultilineGraphQL )
Multiline string kinds.
type MultilineString ¶
type MultilineString struct {
Kind MultilineKind
// Lang is the language hint as written ("" for plain text).
Lang string
// Comma is set when a graphql hint is followed by the optional comma.
Comma bool
Space Whitespace
Newline Whitespace
Value *Template
Variables *GraphQLVariables
}
MultilineString is ```lang? ... ```.
type MultipartField ¶
type MultipartField struct {
Key Text
Value Text
File *MultipartFile
}
MultipartField is one line in [Multipart]: a text field (Value set) or a file field (File set).
type MultipartFile ¶
MultipartFile is a `key: file,name; type` line in [Multipart].
type MultipartParam ¶
type MultipartParam interface {
// contains filtered or unexported methods
}
MultipartParam is a *KeyValue or a *FilenameParam.
type Node ¶
type Node interface {
// contains filtered or unexported methods
}
Node is any AST value that can appear in a polymorphic position.
type Number ¶
type Number struct {
Kind NumberKind
Int int64
Float float64
Source string
}
Number is a numeric literal with its source text.
type NumberKind ¶
type NumberKind int
NumberKind distinguishes number representations.
const ( NumberInteger NumberKind = iota NumberFloat NumberBigInteger )
Number kinds.
type Option ¶
type Option struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Name string
Space1 Whitespace
Space2 Whitespace
// Value is *Template (strings, filenames), *Boolean, *Number, *Duration,
// *Placeholder, *VariableDefinition or *Identifier (verbosity).
Value Node
LineTerminator0 *LineTerminator
}
Option is one `name: value` line in [Options].
type OptionField ¶
type OptionField struct{ Name, RawValue string }
OptionField is one line in [Options]. Name is the option's grammar name (e.g. "compressed", "retry", "variable"); RawValue is its source text, written as is. Build one with BoolOption, IntOption, DurationOption, StringOption, FilenameOption or VariableOption, which escape the value.
func BoolOption ¶
func BoolOption(name string, v bool) OptionField
BoolOption is a boolean option, e.g. `insecure: true`.
func DurationOption ¶
func DurationOption(name string, d time.Duration) OptionField
DurationOption is a duration option, in seconds when d is whole seconds and in milliseconds otherwise, e.g. `connect-timeout: 5s`.
func FilenameOption ¶
func FilenameOption(name string, path Text) OptionField
FilenameOption is a file name option, e.g. `cacert: ca.pem`.
func IntOption ¶
func IntOption(name string, n int64) OptionField
IntOption is an integer option, e.g. `max-redirs: 5`.
func StringOption ¶
func StringOption(name string, v Text) OptionField
StringOption is a string option, e.g. `proxy: localhost:3128`.
func VariableOption ¶
func VariableOption(name string, v Text) OptionField
VariableOption is a `variable: name="value"` option; the value is always a string.
type Placeholder ¶
type Placeholder struct {
Space0 Whitespace
Expr Expr
Space1 Whitespace
// Trailing is text after the expression inside a string placeholder,
// e.g. "b" in "{{a b}}". It is accepted and ignored for compatibility,
// and kept for printing.
Trailing string
}
Placeholder is `{{ expr }}`.
type Pos ¶
Pos is a position in a source file. Offset (bytes) is canonical; Line and Col are 1-based, with Col counted in runes (combining diacritical marks do not advance it).
type Predicate ¶
type Predicate struct {
Not bool
Space0 Whitespace // after `not`
Func *PredicateFunc
}
Predicate is `not? func value?`.
type PredicateFunc ¶
type PredicateFunc struct {
Span Span
Kind PredicateKind
Space0 Whitespace
Value PredicateValue // nil for value-less predicates
}
PredicateFunc is a predicate keyword with its optional value.
type PredicateKind ¶
type PredicateKind int
PredicateKind identifies a predicate function; String returns its keyword.
const ( PredicateEqual PredicateKind = iota PredicateNotEqual PredicateGreater PredicateGreaterOrEqual PredicateLess PredicateLessOrEqual PredicateStartWith PredicateEndWith PredicateContain PredicateInclude PredicateMatch PredicateExist PredicateIsBoolean PredicateIsCollection PredicateIsDate PredicateIsEmpty PredicateIsFloat PredicateIsInteger PredicateIsIPv4 PredicateIsIPv6 PredicateIsIsoDate PredicateIsList PredicateIsNumber PredicateIsObject PredicateIsString PredicateIsUUID )
Predicate kinds.
func (PredicateKind) String ¶
func (k PredicateKind) String() string
type PredicateValue ¶
type PredicateValue interface {
Node
// contains filtered or unexported methods
}
PredicateValue is one of *Null, *Boolean, *Number, *Template (quoted or backtick), *MultilineString, *Base64, *Hex, *FileRef, *Placeholder, *Regex.
type Query ¶
type Query struct {
Span Span
Kind QueryKind
Space0 Whitespace
Arg Node
}
Query extracts a value from the response. Queries with an argument have Space0 before it.
type QueryKind ¶
type QueryKind int
QueryKind identifies a query; String returns its keyword.
const ( QueryStatus QueryKind = iota QueryVersion QueryURL QueryHeader // Arg: *Template QueryCookie // Arg: *CookiePath QueryBody QueryXPath // Arg: *Template QueryJSONPath // Arg: *Template QueryRegex // Arg: *Template or *Regex QueryVariable // Arg: *Template QueryDuration QueryBytes QueryRawBytes QuerySHA256 QueryMD5 QueryCertificate // Arg: *CertificateAttribute QueryIP QueryRedirects QuerySondeStream // Arg: nil or *StreamField; .sonde only QuerySondeGrpc // Arg: nil or *StreamField; .sonde only )
Query kinds.
type Request ¶
type Request struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Method Method
Space1 Whitespace
URL *Template
LineTerminator0 *LineTerminator
Headers []*KeyValue
Sections []*Section
Body *Body
Span Span
}
Request is the request part of an entry.
type Response ¶
type Response struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Version Version
Space1 Whitespace
Status Status
LineTerminator0 *LineTerminator
Headers []*KeyValue
Sections []*Section
Body *Body
Span Span
}
Response is the expected response part of an entry.
type ResponseSpec ¶
type ResponseSpec struct{ Status string }
ResponseSpec is an entry's expected response: its status only (as digits, or "*" for any status); assertions are not built here.
type Section ¶
type Section struct {
LineTerminators []*LineTerminator
Space0 Whitespace
Kind SectionKind
Name string // as written, e.g. "Query" or "QueryStringParams"
Span Span // the `[Name]` header
LineTerminator0 *LineTerminator
KeyValues []*KeyValue
Multipart []MultipartParam
Options []*Option
Captures []*Capture
Asserts []*Assert
Messages []*MessageStep
}
Section is `[Name]` followed by its items. Only the slice matching Kind is set: KeyValues (query, form, cookies, basic auth — at most one), Multipart, Options, Captures, Asserts or Messages.
type SectionKind ¶
type SectionKind int
SectionKind identifies a request or response section.
const ( SectionQueryParams SectionKind = iota SectionFormParams SectionMultipart SectionCookies SectionBasicAuth SectionOptions SectionCaptures SectionAsserts SectionMessages // [SondeMessages], .sonde only SectionGrpc // [SondeGrpc], .sonde only: KeyValues )
Section kinds.
type StepKind ¶ added in v1.2.0
type StepKind int
StepKind identifies a [SondeMessages] step; String returns its keyword.
type StreamField ¶ added in v1.2.0
type StreamField struct {
Name string
}
StreamField is the quoted field of a sondeStream or sondeGrpc query, e.g. "event" (stored without quotes).
type Template ¶
type Template struct {
Delimiter rune
Elements []TemplateElement
Span Span
}
Template is a string made of literal parts and {{ }} placeholders. Delimiter is '"' or '`' for quoted strings, 0 when unquoted.
type TemplateElement ¶
type TemplateElement interface {
// contains filtered or unexported methods
}
TemplateElement is a *TemplateString or a *Placeholder.
type TemplateString ¶
TemplateString is a literal part: decoded Value and its Source text (escaped as written). Print uses Source.
type Text ¶
type Text []TextElem
Text is a value made of literal parts and {{variable}} placeholders, e.g. Text{Lit("Bearer "), Var("token")}.
type TextElem ¶
type TextElem struct {
// contains filtered or unexported fields
}
TextElem is one part of a Text value: a literal chunk or a {{variable}} placeholder. Use Lit and Var to build one.
type VariableDefinition ¶
type VariableDefinition struct {
Span Span
Name string
Space0 Whitespace
Space1 Whitespace
// Value is *Null, *Boolean, *Number or *Template.
Value Node
}
VariableDefinition is `name = value` in a variable option.
type Version ¶
Version is the response HTTP version: "HTTP", "HTTP/1.0", "HTTP/1.1", "HTTP/2" or "HTTP/3".
type Whitespace ¶
Whitespace is a run of spaces/tabs (or newlines inside JSON-like values).