github.com/mitranim/sqlb@v0.7.2/sqlb.go (about)

     1  package sqlb
     2  
     3  import r "reflect"
     4  
     5  /*
     6  Enables validation of unused arguments in parametrized queries generated via
     7  `ListQ` / `DictQ` / `StructQ` / `StrQ` / `Preparse` / `Prep`. By default,
     8  validation is enabled. It can be disabled in two ways: globally by changing
     9  this variable to `false`, or by using an argument dictionary without support
    10  for argument validation, such as `LaxDict`.
    11  */
    12  var ValidateUnusedArguments = true
    13  
    14  /*
    15  Short for "expression". Defines an arbitrary SQL expression. The method appends
    16  arbitrary SQL text. In both the input and output, the arguments must correspond
    17  to the parameters in the SQL text. Different databases support different styles
    18  of ordinal parameters. This package always generates Postgres-style ordinal
    19  parameters such as "$1", renumerating them as necessary.
    20  
    21  This method is allowed to panic. Use `(*Bui).CatchExprs` to catch
    22  expression-encoding panics and convert them to errors.
    23  
    24  All `Expr` types in this package also implement `AppenderTo` and `fmt.Stringer`.
    25  */
    26  type Expr interface {
    27  	AppendExpr([]byte, []any) ([]byte, []any)
    28  }
    29  
    30  /*
    31  Short for "parametrized expression". Similar to `Expr`, but requires an external
    32  input in order to be a valid expression. Implemented by preparsed query types,
    33  namely by `Prep`.
    34  */
    35  type ParamExpr interface {
    36  	AppendParamExpr([]byte, []any, ArgDict) ([]byte, []any)
    37  }
    38  
    39  /*
    40  Appends a text repesentation. Sometimes allows better efficiency than
    41  `fmt.Stringer`. Implemented by all `Expr` types in this package.
    42  */
    43  type AppenderTo interface{ AppendTo([]byte) []byte }
    44  
    45  /*
    46  Dictionary of arbitrary arguments, ordinal and/or named. Used as input to
    47  `ParamExpr` (parametrized expressions). This package provides multiple
    48  implementations: slice-based `List`, map-based `Dict`, and struct-based
    49  `StructDict`. May optionally implement `OrdinalRanger` and `NamedRanger` to
    50  validate used/unused arguments.
    51  */
    52  type ArgDict interface {
    53  	IsEmpty() bool
    54  	Len() int
    55  	GotOrdinal(int) (any, bool)
    56  	GotNamed(string) (any, bool)
    57  }
    58  
    59  /*
    60  Optional extension for `ArgDict`. If implemented, this is used to validate
    61  used/unused ordinal arguments after building a parametrized SQL expression such
    62  as `StrQ`/`Prep`.
    63  */
    64  type OrdinalRanger interface {
    65  	/**
    66  	Must iterate over argument indexes from 0 to N, calling the function for each
    67  	index. The func is provided by this package, and will panic for each unused
    68  	argument.
    69  	*/
    70  	RangeOrdinal(func(int))
    71  }
    72  
    73  /*
    74  Optional extension for `ArgDict`. If implemented, this is used to validate
    75  used/unused named arguments after building a parametrized SQL expression such
    76  as `StrQ`/`Prep`.
    77  */
    78  type NamedRanger interface {
    79  	/**
    80  	Must iterate over known argument names, calling the function for each name.
    81  	The func is provided by this package, and will panic for each unused
    82  	argument.
    83  	*/
    84  	RangeNamed(func(string))
    85  }
    86  
    87  /*
    88  Used by `Partial` for filtering struct fields. See `Sparse` and `Partial` for
    89  explanations.
    90  */
    91  type Haser interface{ Has(string) bool }
    92  
    93  /*
    94  Represents an arbitrary struct where not all fields are "present". Calling
    95  `.Get` returns the underlying struct value. Calling `.AllowField` answers the
    96  question "is this field present?".
    97  
    98  Secretly supported by struct-scanning expressions such as `StructInsert`,
    99  `StructAssign`, `StructValues`, `Cond`, and more. These types attempt to upcast
   100  the inner value to `Sparse`, falling back on using the inner value as-is. This
   101  allows to correctly implement REST "PATCH" semantics by using only the fields
   102  that were present in a particular HTTP request, while keeping this
   103  functionality optional.
   104  
   105  Concrete implementation: `Partial`.
   106  */
   107  type Sparse interface {
   108  	Filter
   109  	Get() any
   110  }
   111  
   112  /*
   113  Filters struct fields. Used by `Sparse` and `ParseOpt`. Implemented by
   114  `TagFilter`.
   115  */
   116  type Filter interface{ AllowField(r.StructField) bool }
   117  
   118  /*
   119  Optional interface that allows `sqlb` to determine if a given value is null,
   120  allowing some expressions to generate `is null` / `is not null` clauses. Not
   121  actually required; nils of Go nilable types are automatically considered null,
   122  and `sqlb` falls back on encoding the value via `driver.Valuer`. This interface
   123  is supported for additional flexibility and efficiency.
   124  */
   125  type Nullable interface{ IsNull() bool }