types.go

// Copyright 2026 The Zaparoo Project Contributors.
// SPDX-License-Identifier: Apache-2.0
//
// 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.

// Package zapscript provides a parser for ZapScript, a custom scripting language
// for launching games and executing commands through physical tokens.
package zapscript

// TagOperator defines the logical operator for tag filtering.
type TagOperator string

const (
	TagOperatorAND TagOperator = "AND"
	TagOperatorNOT TagOperator = "NOT"
	TagOperatorOR  TagOperator = "OR"
)

// TagFilter represents a filter for matching media by tags.
type TagFilter struct {
	Type     string
	Value    string
	Operator TagOperator
}

// Key is a typed key for advanced argument map lookups.
type Key string

// Argument key constants for advarg struct tags and map lookups.
const (
	KeyWhen           Key = "when"
	KeyLauncher       Key = "launcher"
	KeySystem         Key = "system"
	KeyAction         Key = "action"
	KeySetName        Key = "set_name"
	KeySetNameSameDir Key = "set_name_same_dir"
	KeySlot           Key = "slot"
	KeyTags           Key = "tags"
	KeyMode           Key = "mode"
	KeyRepeat         Key = "repeat"
	KeyName           Key = "name"
	KeyPreNotice      Key = "pre_notice"
	KeyHidden         Key = "hidden"
)

// Action values for the action advanced argument.
const (
	// ActionRun is the default action - launch/play the media.
	ActionRun = "run"
	// ActionDetails shows the media details/info page instead of launching.
	ActionDetails = "details"
)

// Mode values for the mode advanced argument.
const (
	// ModeShuffle randomizes playlist order.
	ModeShuffle = "shuffle"
)

// Repeat values for the repeat advanced argument.
const (
	// RepeatOff stops playback at the end of the playlist (default).
	RepeatOff = "off"
	// RepeatAll loops the whole playlist back to the start when it ends.
	RepeatAll = "all"
	// RepeatOne repeats the current track indefinitely.
	RepeatOne = "one"
)

// GlobalArgs contains advanced arguments available to all commands.
type GlobalArgs struct {
	// When controls conditional execution. If non-empty and falsy, command is skipped.
	When string `advarg:"when"`
}

// LaunchArgs contains advanced arguments for the launch command.
type LaunchArgs struct {
	GlobalArgs
	// SetName specifies a platform-defined launch profile/core name override.
	SetName string `advarg:"set_name"`
	// SetNameSameDir controls whether SetName should keep the original game directory.
	SetNameSameDir string `advarg:"set_name_same_dir"`
	// Launcher overrides the default launcher by ID.
	Launcher string `advarg:"launcher" validate:"omitempty,launcher"` //nolint:revive // custom validator
	// System specifies the target system for path resolution.
	System string `advarg:"system" validate:"omitempty,system"` //nolint:revive // custom validator
	// Action specifies the launch action (run, details).
	Action string `advarg:"action" validate:"omitempty,oneof=run details"`
	// Slot selects the media slot for launch routing.
	Slot string `advarg:"slot"`
	// Name is the filename for remote file installation.
	Name string `advarg:"name"`
	// PreNotice is shown before remote file download.
	PreNotice string `advarg:"pre_notice"`
}

// LaunchRandomArgs contains advanced arguments for the launch.random command.
type LaunchRandomArgs struct {
	GlobalArgs
	// SetName specifies a platform-defined launch profile/core name override.
	SetName string `advarg:"set_name"`
	// SetNameSameDir controls whether SetName should keep the original game directory.
	SetNameSameDir string `advarg:"set_name_same_dir"`
	// Launcher overrides the default launcher by ID.
	Launcher string `advarg:"launcher" validate:"omitempty,launcher"` //nolint:revive // custom validator
	// Action specifies the launch action (run, details).
	Action string `advarg:"action" validate:"omitempty,oneof=run details"`
	// Slot selects the media slot for launch routing.
	Slot string `advarg:"slot"`
	// Tags filters results by tag criteria.
	Tags []TagFilter `advarg:"tags"`
}

// LaunchSearchArgs contains advanced arguments for the launch.search command.
type LaunchSearchArgs struct {
	GlobalArgs
	// SetName specifies a platform-defined launch profile/core name override.
	SetName string `advarg:"set_name"`
	// SetNameSameDir controls whether SetName should keep the original game directory.
	SetNameSameDir string `advarg:"set_name_same_dir"`
	// Launcher overrides the default launcher by ID.
	Launcher string `advarg:"launcher" validate:"omitempty,launcher"` //nolint:revive // custom validator
	// Action specifies the launch action (run, details).
	Action string `advarg:"action" validate:"omitempty,oneof=run details"`
	// Slot selects the media slot for launch routing.
	Slot string `advarg:"slot"`
	// Tags filters results by tag criteria.
	Tags []TagFilter `advarg:"tags"`
}

// LaunchTitleArgs contains advanced arguments for the launch.title command.
type LaunchTitleArgs struct {
	GlobalArgs
	// SetName specifies a platform-defined launch profile/core name override.
	SetName string `advarg:"set_name"`
	// SetNameSameDir controls whether SetName should keep the original game directory.
	SetNameSameDir string `advarg:"set_name_same_dir"`
	// Launcher overrides the default launcher by ID.
	Launcher string `advarg:"launcher" validate:"omitempty,launcher"` //nolint:revive // custom validator
	// Action specifies the launch action (run, details).
	Action string `advarg:"action" validate:"omitempty,oneof=run details"`
	// Slot selects the media slot for launch routing.
	Slot string `advarg:"slot"`
	// Tags filters results by tag criteria.
	Tags []TagFilter `advarg:"tags"`
}

// LaunchLastArgs contains advanced arguments for the launch.last command.
type LaunchLastArgs struct {
	GlobalArgs
	// SetName specifies a platform-defined launch profile/core name override.
	SetName string `advarg:"set_name"`
	// SetNameSameDir controls whether SetName should keep the original game directory.
	SetNameSameDir string `advarg:"set_name_same_dir"`
	// Launcher overrides the default launcher by ID.
	Launcher string `advarg:"launcher" validate:"omitempty,launcher"` //nolint:revive // custom validator
	// Action specifies the launch action (run, details).
	Action string `advarg:"action" validate:"omitempty,oneof=run details"`
	// Slot selects the media slot for launch routing.
	Slot string `advarg:"slot"`
}

// PlaylistArgs contains advanced arguments for playlist commands.
type PlaylistArgs struct {
	GlobalArgs
	// Mode controls playlist behavior (e.g., "shuffle").
	Mode string `advarg:"mode" validate:"omitempty,oneof=shuffle"`
	// Repeat controls end-of-playlist behaviour: off (default), all (loop playlist), one (repeat track).
	Repeat string `advarg:"repeat" validate:"omitempty,oneof=off all one"`
	// Slot selects the media slot for playlist routing.
	Slot string `advarg:"slot"`
}

// MisterScriptArgs contains advanced arguments for MiSTer script commands.
type MisterScriptArgs struct {
	GlobalArgs
	// Hidden controls whether the script window is hidden.
	Hidden string `advarg:"hidden"`
}