upsert

Documentation

Index

• type Option
  • func DisableSetting(setting Setting) Option
  • func EnableSetting(setting Setting) Option
  • func EnableSettingIf(setting Setting, boolean bool) Option
  • func WithGroup(name string) Option
  • func WithPlacement(placement Placement) Option
  • func WithPlacementIgnoringEmpty(placement Placement, key string) Option
  • func WithPlacementInGroup(placement Placement, key string) Option
  • func WithPlacementInGroupIgnoringEmpty(placement Placement, key string) Option
  • func WithPlacementRelativeToKey(placement Placement, key string) Option
  • func WithSkipValidationRule(rules ...string) Option
• type Placement
  • func (p Placement) RequiresKey() bool
  • func (p Placement) String() string
• type Setting
  • func (bitmask Setting) Has(setting Setting) bool
  • func (setting Setting) String() string
• type SkippedStatementError
  • func (e SkippedStatementError) Error() string
• type Upserter
  • func New(document *ast.Document, options ...Option) (*Upserter, error)
  • func (u *Upserter) ApplyOptions(options ...Option) error
  • func (u *Upserter) Upsert(ctx context.Context, input *ast.Assignment) (*ast.Assignment, error)

Types

type Option

type Option func(*Upserter) error

Option is used to configure the Upserter

func DisableSetting

func DisableSetting(setting Setting) Option

WithSetting will remove the provided Setting in the Upserter settings bitmask.

func EnableSetting

func EnableSetting(setting Setting) Option

EnableSetting will set the provided Setting in the Upserter settings bitmask.

func EnableSettingIf

func EnableSettingIf(setting Setting, boolean bool) Option

EnableSettingIf will, depending on [boolean], either enable or disable a Upserter setting. Its mainly a convenience function to avoid if/else on the caller side - such as in cases of bool CLI flags changing controlling a setting.

func WithGroup

func WithGroup(name string) Option

WithGroup configures the Upserter to the new ast.Assignment to this group when creating it within the ast.Document

func WithPlacement

func WithPlacement(placement Placement) Option

WithPlacementKey configures the Upserter to add a new KEY in a relative place within a document, if the KEY does not already exists.

func WithPlacementIgnoringEmpty

func WithPlacementIgnoringEmpty(placement Placement, key string) Option

WithPlacementIgnoringEmpty is like WithPlacement but is NOOP if the KEY is an empty string. Mostly useful convenience method for passing through CLI flags directly.

func WithPlacementInGroup

func WithPlacementInGroup(placement Placement, key string) Option

WithPlacementInGroup is like WithPlacement but further more configures the KEY's group (if any) as well

func WithPlacementInGroupIgnoringEmpty

func WithPlacementInGroupIgnoringEmpty(placement Placement, key string) Option

WithPlacementInGroupIgnoringEmpty is like WithPlacementInGroup but is NOOP if the KEY is an empty string. Mostly useful convenience method for passing through CLI flags directly.

func WithPlacementRelativeToKey

func WithPlacementRelativeToKey(placement Placement, key string) Option

WithPlacementRelativeToKey configures the Upserter to add a new KEY in a specific place (in relation to the provided KEY) within a document, if the KEY does not already exists.

func WithSkipValidationRule

func WithSkipValidationRule(rules ...string) Option

WithSkipValidationRule allow you to skip/ignore specific validation rules

type Placement

type Placement uint

Placement is a setting for deciding where a *new* KEY should be added within the document/group it's targeting When a KEY already exists, its placement will not be updated

const (
	// NOTE: [AddLast] is the *default* when not configured in the [Upserter] (since its the 'empty' type of int aka '0')
	AddLast Placement = iota
	AddAfterKey
	AddBeforeKey
	AddFirst
)

func (Placement) RequiresKey

func (p Placement) RequiresKey() bool

func (Placement) String

func (p Placement) String() string

type Setting

type Setting int

Setting is a bitmask for controlling Upsert behavior

const (
	// SkipIfSame will skip the upsert operation if the incoming KEY+VALUE is identical to the one in the document.
	// This is mostly used in the [update] command where it would not emit a "changed" event.
	SkipIfSame Setting = 1 << iota

	// SkipIfExists will skip the upsert operation if the KEY exists in the document (empty or not).
	// This is useful for adding new KEY to the config file (e.g. during migration/upgrade), but never changing the key
	// if it already exists, regardless of the VALUE/Assignment configuration
	SkipIfExists

	// SkipIfSet will skip the upsert operation if the KEY exists in the document and *NOT* empty.
	SkipIfSet

	// SkipIfEmpty will skip the upsert operation if the KEY VALUE is empty
	SkipIfEmpty

	// Validate the KEY/VALUE pair and fail the operation if its invalid
	Validate

	// ErrorIfMissing will abort if the KEY does *NOT* exists in the target document. This is useful for ensuring
	// you only update keys, not accidentally creating new keys (e.g. in case of a typo).
	ErrorIfMissing

	// Replace comments on *existing* Assignments.
	//
	// Normally comments are only applied to *NEW* keys and not on existing ones.
	UpdateComments
)

func (Setting) Has

func (bitmask Setting) Has(setting Setting) bool

Has checks if [check] exists in the [settings] bitmask or not.

func (Setting) String

func (setting Setting) String() string

Pretty-print Setting value, both for single and multiple keys

type SkippedStatementError

type SkippedStatementError struct {
	Key     string
	Reason  string
	IsError bool
}

func (SkippedStatementError) Error

func (e SkippedStatementError) Error() string

type Upserter

type Upserter struct {
	// contains filtered or unexported fields
}

func New

func New(document *ast.Document, options ...Option) (*Upserter, error)

New creates an Upserter with the provided settings, returning either the Upserter or an error if an Option validation failed

func (*Upserter) ApplyOptions

func (u *Upserter) ApplyOptions(options ...Option) error

ApplyOptions applies any additional options to the Upserter, allowing you to refine and build the Upserter in steps.

func (*Upserter) Upsert

func (u *Upserter) Upsert(ctx context.Context, input *ast.Assignment) (*ast.Assignment, error)

Upsert will, depending on its options, either Update or Insert (thus, "[Up]date + In[sert]").