README
¶
List Filter Parser
Experimental, may change in backwards-incompatible ways
A library for parsing filter expressions as found in list and search web calls.
License
Copyright 2022 Hayo van Loon
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Package listfilter implements a query parser and the resulting filter as used in List and Search requests.
Syntax and semantics are reverse engineered (and expanded upon) from: https://cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services/search#query-parameters
Examples of filter strings:
"foo=bar" "foo.bar=bla" "foo=bar AND bla=vla" "foo>bar AND foo=bar" "foo>bar AND foo=bar OR moo=boo"
The filter string should adher to the following grammar:
Filter = <nil> | Conditions
Conditions = Condition { Separator Conditions }
Separator = Space SeparatorToken Space
SeparatorToken 'AND' | 'OR'
Condition = FullName Operator Value
FullName = NameParts
NameParts = Name | Name NameSeparator NameParts
NameSeparator = '.'
Name = regex([a-zA-Z][a-zA-Z0-9_]*)
Operator = regex([^a-zA-Z0-9_].*)
Value = NormalValue | QuotedValue
NormalValue = [^separator\s"] { regex([^separator\s]*) }
QuotedValue = '"' Escaped '"'
Escaped = <nil> | NormalChar Escaped | EscapedChar Escaped
EscapedChar = '\\' | '\"' NormalChar | <not eChar>
An empty string is considered a valid input and will result in an empty Filter.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Condition ¶
type Condition interface {
// Key returns the condition's key.
Key() string
// KeyParts returns the condition's key part list, which has at least one item.
KeyParts() []string
// Op returns the condition's operator as a string.
Op() string
// StringValue returns the raw string value of the condition.
StringValue() string
// IntValue is a convenience function for getting a filter condition value as an
// integer. If the value is not an integer, an error is returned.
IntValue() (int, error)
// BoolValue is a convenience function for getting a filter condition value as
// a boolean. If the value is not a strict boolean (case-insensitive 'true' or
// 'false'), an error is returned.
BoolValue() (bool, error)
// FloatValue is a convenience function for getting a filter condition value as
// a 64-bit float. If the value is not a float, an error is returned.
FloatValue() (float64, error)
// And returns the next AND Condition, if there is one, nil otherwise.
And() Condition
// Or returns the next OR Condition, if there is one, nil otherwise.
Or() Condition
// AndOr returns the next condition in the filter. It returns a tuple; the
// first points to an AND condition, the second to an OR.
AndOr() (Condition, Condition)
}
Condition stores a filter condition.
type Filter ¶
type Filter interface {
// Get retrieves the conditions for a given key.
Get(k string) ([]Condition, bool)
// GetFirst retrieves the first condition for a given key.
GetFirst(k string) (Condition, bool)
// GetLast retrieves the last condition for a given key.
GetLast(k string) (Condition, bool)
// Keys returns all Condition keys found in the filter.
Keys() []string
// Values returns every Condition found in the filter. Other than that
// conditions are grouped in blocks with the same key, there are no guarantees
// on ordering. If for instance insertion order is required, use Conditions.
Values() []Condition
// Len returns the number of keys in the filter. This is may be less than
// the total number of conditions.
Len() int
// First returns the first condition (as encountered in the original string).
// Starting from this Condition and moving through its Condition.AndOr method
// will allow reconstruction of the original filter string.
First() Condition
// Conditions returns all conditions by order of appearance in the original
// filter string.
Conditions() []Condition
fmt.Stringer
}
A Filter is a container for filter conditions as parsed by the Parser.
type Option ¶ added in v0.2.0
type Option interface {
Apply(parser *parser)
}
An Option that can be passed to the NewParser factory method.
func OptionCamelCase ¶ added in v0.2.0
func OptionCamelCase() Option
OptionCamelCase will instruct the parser to make a best-effort attempt at converting field names to camelCase. Cannot be used along with OptionSnakeCase.
func OptionSnakeCase ¶ added in v0.2.0
func OptionSnakeCase() Option
OptionSnakeCase will instruct the parser to make a best-effort attempt at converting field names to snake_case. Cannot be used along with OptionCamelCase. When an uppercase character is encountered, it will be lower-cased. It will be prefixed with an underscore, unless it is the starting character, preceded by another uppercase character, or preceded by an underscore.
type ParseError ¶
type ParseError interface {
error
// Message provides a user-friendly error message.
Message() string
// Position returns the position in the string at which parsing failed.
Position() int
// Unparsable returns the part of the string from which parsing failed.
Unparsable() string
}
A ParseError describes the error that occurred while parsing. In addition, it provides details to help pinpoint the error.
type Parser ¶ added in v0.3.0
type Parser interface {
// Parse parses a filter string into a Filter.
Parse(s string) (Filter, error)
}
A Parser parses a filter string into a Filter. If parsing fails, an error is returned and the Filter will be nil. The error will be a ParseError, which has methods for diagnosing the parsing failure.
Source Files