github.com/blend/go-sdk@v1.20240719.1/selector/parse.go (about)

     1  /*
     2  
     3  Copyright (c) 2024 - Present. Blend Labs, Inc. All rights reserved
     4  Use of this source code is governed by a MIT license that can be found in the LICENSE file.
     5  
     6  */
     7  
     8  package selector
     9  
    10  // Parse takes a string representing a selector and returns a selector
    11  // object, or an error.
    12  // The input will cause an error if it does not follow this form:
    13  //
    14  //	<selector-syntax>         ::= <requirement> | <requirement> "," <selector-syntax>
    15  //	<requirement>             ::= [!] KEY [ <set-based-restriction> | <exact-match-restriction> ]
    16  //	<set-based-restriction>   ::= "" | <inclusion-exclusion> <value-set>
    17  //	<inclusion-exclusion>     ::= <inclusion> | <exclusion>
    18  //	<exclusion>               ::= "notin"
    19  //	<inclusion>               ::= "in"
    20  //	<value-set>               ::= "(" <values> ")"
    21  //	<values>                  ::= VALUE | VALUE "," <values>
    22  //	<exact-match-restriction> ::= ["="|"=="|"!="] VALUE
    23  //
    24  // KEY is a sequence of one or more characters following: [ DNS_SUBDOMAIN "/" ] DNS_LABEL.
    25  //   - DNS_SUBDOMAIN is a sequence of one or more characters ([a-z0-9-.]), and must start and end with an alphanumeric ([a-z0-9]).
    26  //     Symbol characters ('.', '-') cannot repeat. Max length is 253 characters.
    27  //   - DNS_LABEL is a sequence of one or more characters ([A-Za-z0-9_-.]). Max length is 63 characters.
    28  //
    29  // VALUE is a sequence of zero or more characters ([A-Za-z0-9_-.]). Values must start and end with an alphanumeric ([a-z0-9A-Z]). Max length is 63 characters.
    30  // Delimiter is white space: (' ', '\t')
    31  //
    32  // Example of valid syntax:
    33  //
    34  //	"x in (foo,,baz),y,z notin ()"
    35  //
    36  // Note:
    37  //
    38  //	(1) Inclusion - " in " - denotes that the KEY exists and is equal to any of the
    39  //	    VALUEs in its requirement
    40  //	(2) Exclusion - " notin " - denotes that the KEY is not equal to any
    41  //	    of the VALUEs in its requirement or does not exist
    42  //	(3) The empty string is a valid VALUE
    43  //	(4) A requirement with just a KEY - as in "y" above - denotes that
    44  //	    the KEY exists and can be any VALUE.
    45  //	(5) A requirement with just !KEY requires that the KEY not exist.
    46  func Parse(query string, opts ...Option) (Selector, error) {
    47  	p := &Parser{s: query}
    48  	for _, opt := range opts {
    49  		opt(p)
    50  	}
    51  	return p.Parse()
    52  }
    53  
    54  // MustParse parses the selector but will panic if there is an issue.
    55  func MustParse(query string, opts ...Option) Selector {
    56  	sel, err := Parse(query, opts...)
    57  	if err != nil {
    58  		panic(err)
    59  	}
    60  	return sel
    61  }