AcediaFramework
/
AcediaCore
2
0
Fork 0
Code Issues 9 Pull Requests Releases Wiki Activity
Browse Source

Fix style for remaining `CommandAPI`-related classes

pull/12/head
Anton Tarasenko 2 years ago
parent
c4247a67d0
commit
677dd84e90
2 changed files with 513 additions and 697 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 492
      sources/BaseAPI/API/Commands/Command.uc
  2. 350
      sources/BaseAPI/API/Commands/PlayersParser.uc

492
sources/BaseAPI/API/Commands/Command.uc
Unescape View File

@ -1,12 +1,8 @@
/**
* This class is meant to represent a command type: to create new command
* one should extend it, then simply define required sub-commands/options and
* parameters in `BuildData()` and overload `Executed()` / `ExecutedFor()`
* to perform required actions when command is executed by a player.
* `Executed()` is called first, whenever command is executed and
* `ExecuteFor()` is called only for targeted commands, once for each
* targeted player.
* Copyright 2021-2022 Anton Tarasenko
* Author: dkanus
* Home repo: https://www.insultplayers.ru/git/AcediaFramework/AcediaCore
* License: GPL
* Copyright 2021-2023 Anton Tarasenko
*------------------------------------------------------------------------------
* This file is part of Acedia.
*
@ -26,79 +22,57 @@
class Command extends AcediaObject
dependson(BaseText);
/**
* # `Command`
*
* Command class provides an automated way to add a command to a server through
* AcediaCore's features. It takes care of:
*
* 1. Verifying that player has passed correct (expected parameters);
* 2. Parsing these parameters into usable values (both standard, built-in
* types like `bool`, `int`, `float`, etc. and more advanced types such
* as players lists and JSON values);
* 3. Allowing you to easily specify a set of players you are targeting by
* supporting several ways to refer to them, such as *by name*, *by id*
* and *by selector* (@ and @self refer to caller player, @all refers
* to all players).
* 4. It can be registered inside AcediaCore's commands feature and be
* automatically called through the unified system that supports *chat*
* and *mutate* inputs (as well as allowing you to hook in any other
* input source);
* 5. Will also automatically provide a help page through built-in "help"
* command;
* 6. Subcommand support - when one command can have several distinct
* functions, depending on how its called (e.g. "inventory add" vs
* "inventory remove"). These subcommands have a special treatment in
* help pages, which makes them more preferable, compared to simply
* matching first `Text` argument;
* 7. Add support for "options" - additional flags that can modify commands
* behavior and behave like usual command options "--force"/"-f".
* Their short versions can even be combined:
* "give@ $ebr --ammo --force" can be rewritten as "give@ $ebr -af".
* And they can have their own parameters: "give@all --list sharp".
*
* ## Usage
*
* To create a custom command you need to simply:
*
* 1. Create a custom command class derived from `Command`;
* 2. Define `BuildData()` function and use given `CommandDataBuilder` to
* fill-in data about what parameters your command takes. You can also
* add optional descriptions that would appear in your command's
* help page.
* 3. Overload `Executed()` or `ExecutedFor()` (or both) method and add
* whatever logic you want to execute once your command was called.
* All parameters and options will be listed inside passed `CallData`
* parameter. These methods will only be called if all necessary
* parameters were correctly specified.
*
* ## Implementation
*
* The idea of `Command`'s implementation is simple: command is basically
* the `Command.Data` struct that is filled via `CommandDataBuilder`.
* Whenever command is called it uses `CommandParser` to parse user's input
* based on its `Command.Data` and either report error (in case of failure) or
* pass make `Executed()`/`ExecutedFor()` calls (in case of success).
* When command is called is decided by `Commands_Feature` that tracks
* possible user inputs (and provides `HandleInput()`/`HandleInputWith()`
* methods for adding custom command inputs). That feature basically parses
* first part of the command: its name (not the subcommand's names) and target
* players (using `PlayersParser`, but only if command is targeted).
*
* Majority of the command-related code either serves to build
* `Command.Data` or to parse command input by using it (`CommandParser`).
*/
/**
* Possible errors that can arise when parsing command parameters from
* user input
*/
enum ErrorType
{
//! This class is meant to represent a command type.
//!
//! Command class provides an automated way to add a command to a server through
//! AcediaCore's features. It takes care of:
//!
//! 1. Verifying that player has passed correct (expected parameters);
//! 2. Parsing these parameters into usable values (both standard, built-in
//! types like `bool`, `int`, `float`, etc. and more advanced types such
//! as players lists and JSON values);
//! 3. Allowing you to easily specify a set of players you are targeting by
//! supporting several ways to refer to them, such as *by name*, *by id*
//! and *by selector* (@ and @self refer to caller player, @all refers
//! to all players).
//! 4. It can be registered inside AcediaCore's commands feature and be
//! automatically called through the unified system that supports *chat*
//! and *mutate* inputs (as well as allowing you to hook in any other
//! input source);
//! 5. Will also automatically provide a help page through built-in "help"
//! command;
//! 6. Subcommand support - when one command can have several distinct
//! functions, depending on how its called (e.g. "inventory add" vs
//! "inventory remove"). These subcommands have a special treatment in
//! help pages, which makes them more preferable, compared to simply
//! matching first `Text` argument;
//! 7. Add support for "options" - additional flags that can modify commands
//! behavior and behave like usual command options "--force"/"-f".
//! Their short versions can even be combined:
//! "give@ $ebr --ammo --force" can be rewritten as "give@ $ebr -af".
//! And they can have their own parameters: "give@all --list sharp".
//!
//! # Implementation
//!
//! The idea of `Command`'s implementation is simple: command is basically the `Command.Data` struct
//! that is filled via `CommandDataBuilder`.
//! Whenever command is called it uses `CommandParser` to parse user's input based on its
//! `Command.Data` and either report error (in case of failure) or pass make
//! `Executed()`/`ExecutedFor()` calls (in case of success).
//!
//! When command is called is decided by `Commands_Feature` that tracks possible user inputs
//! (and provides `HandleInput()`/`HandleInputWith()` methods for adding custom command inputs).
//! That feature basically parses first part of the command: its name (not the subcommand's names)
//! and target players (using `PlayersParser`, but only if command is targeted).
//!
//! Majority of the command-related code either serves to build `Command.Data` or to parse command
//! input by using it (`CommandParser`).
/// Possible errors that can arise when parsing command parameters from user input
enum ErrorType {
// No error
CET_None,
// Bad parser was provided to parse user input
// (this should not be possible)
// Bad parser was provided to parse user input (this should not be possible)
CET_BadParser,
// Sub-command name was not specified or was incorrect
// (this should not be possible)
@ -117,8 +91,8 @@ enum ErrorType
// Part of user's input could not be interpreted as a part of
// command's call
CET_UnusedCommandParameters,
// In one short option specification (e.g. '-lah') several options
// require parameters: this introduces ambiguity and is not allowed
// In one short option specification (e.g. '-lah') several options require parameters:
// this introduces ambiguity and is not allowed
CET_MultipleOptionsWithParams,
// (For targeted commands only)
// Targets are specified incorrectly (or none actually specified)
@ -126,11 +100,8 @@ enum ErrorType
CET_EmptyTargetList
};
/**
* Structure that contains all the information about how `Command` was called.
*/
struct CallData
{
/// Structure that contains all the information about how `Command` was called.
struct CallData {
// Targeted players (if applicable)
var public array<EPlayer> targetPlayers;
// Specified sub-command and parameters/options
@ -145,11 +116,8 @@ struct CallData
var public Text errorCause;
};
/**
* Possible types of parameters.
*/
enum ParameterType
{
/// Possible types of parameters.
enum ParameterType {
// Parses into `BoolBox`
CPT_Boolean,
// Parses into `IntBox`
@ -170,13 +138,9 @@ enum ParameterType
CPT_Players
};
/**
* Possible forms a boolean variable can be used as.
* Boolean parameter can define it's preferred format, which will be used
* for help page generation.
*/
enum PreferredBooleanFormat
{
/// Possible forms a boolean variable can be used as.
/// Boolean parameter can define it's preferred format, which will be used for help page generation.
enum PreferredBooleanFormat {
PBF_TrueFalse,
PBF_EnableDisable,
PBF_OnOff,
@ -184,8 +148,7 @@ enum PreferredBooleanFormat
};
// Defines a singular command parameter
struct Parameter
{
struct Parameter {
// Display name (for the needs of help page displaying)
var Text displayName;
// Type of value this parameter would store
@ -198,21 +161,20 @@ struct Parameter
// (For `CPT_Boolean` type variables only) - preferred boolean format,
// used in help pages
var PreferredBooleanFormat booleanFormat;
// `CPT_Text` can be attempted to be auto-resolved as an alias from
/// some source during parsing. For command to attempt that, this field must
// be not-`none` and contain the name of the alias source (either "weapon",
// "color", "feature", "entity" or some kind of custom alias source name).
// `CPT_Text` can be attempted to be auto-resolved as an alias from some source during parsing.
// For command to attempt that, this field must be not-`none` and contain the name of
// the alias source (either "weapon", "color", "feature", "entity" or some kind of custom alias
// source name).
//
// Only relevant when given value is prefixed with "$" character.
var Text aliasSourceName;
};
// Defines a sub-command of a this command (specified as
// "<command> <sub_command>").
// Using sub-command is not optional, but if none defined
// (in `BuildData()`) / specified by the player - an empty (`name.IsEmpty()`)
// one is automatically created / used.
struct SubCommand
{
// Defines a sub-command of a this command (specified as "<command> <sub_command>").
//
// Using sub-command is not optional, but if none defined (in `BuildData()`) / specified by
// the player - an empty (`name.IsEmpty()`) one is automatically created / used.
struct SubCommand {
// Cannot be `none`
var Text name;
// Can be `none`
@ -223,8 +185,7 @@ struct SubCommand
// Defines command's option (options are specified by "--long" or "-l").
// Options are independent from sub-commands.
struct Option
{
struct Option {
var BaseText.Character shortName;
var Text longName;
var Text description;
@ -235,8 +196,7 @@ struct Option
// Structure that defines what sub-commands and options command has
// (and what parameters they take)
struct Data
{
struct Data {
// Default command name that will be used unless Acedia is configured to
// do otherwise
var protected Text name;
@ -255,38 +215,32 @@ var private Data commandData;
// of `Command`, so we will simply store and reuse one created instance.
var private Command mainInstance;
/**
* When command is being executed we create several instances of
* `ConsoleWriter` that can be used for command output. They will also be
* automatically deallocated once command is executed.
* DO NOT modify them or deallocate any of them manually.
* This should make output more convenient and standardized.
*
* 1. `publicConsole` - sends messages to all present players;
* 2. `callerConsole` - sends messages to the player that
* called the command;
* 3. `targetConsole` - sends messages to the player that is currently
* being targeted (different each call of `ExecutedFor()` and
* `none` during `Executed()` call);
* 4. `othersConsole` - sends messaged to every player that is
* neither "caller" or "target".
*/
// When command is being executed we create several instances of `ConsoleWriter` that can be used
// for command output. They will also be automatically deallocated once command is executed.
//
// DO NOT modify them or deallocate any of them manually.
//
// This should make output more convenient and standardized.
//
// 1. `publicConsole` - sends messages to all present players;
// 2. `callerConsole` - sends messages to the player that called the command;
// 3. `targetConsole` - sends messages to the player that is currently being targeted
// (different each call of `ExecutedFor()` and `none` during `Executed()` call);
// 4. `othersConsole` - sends messaged to every player that is neither "caller" or "target".
var protected ConsoleWriter publicConsole, othersConsole;
var protected ConsoleWriter callerConsole, targetConsole;
protected function Constructor()
{
protected function Constructor() {
local CommandDataBuilder dataBuilder;
dataBuilder =
CommandDataBuilder(_.memory.Allocate(class'CommandDataBuilder'));
dataBuilder = CommandDataBuilder(_.memory.Allocate(class'CommandDataBuilder'));
BuildData(dataBuilder);
commandData = dataBuilder.BorrowData();
dataBuilder.FreeSelf();
dataBuilder = none;
}
protected function Finalizer()
{
protected function Finalizer() {
local int i;
local array<SubCommand> subCommands;
local array<Option> options;
@ -295,8 +249,7 @@ protected function Finalizer()
_.memory.Free(commandData.name);
_.memory.Free(commandData.summary);
subCommands = commandData.subCommands;
for (i = 0; i < options.length; i += 1)
{
for (i = 0; i < options.length; i += 1) {
_.memory.Free(subCommands[i].name);
_.memory.Free(subCommands[i].description);
CleanParameters(subCommands[i].required);
@ -306,8 +259,7 @@ protected function Finalizer()
}
commandData.subCommands.length = 0;
options = commandData.options;
for (i = 0; i < options.length; i += 1)
{
for (i = 0; i < options.length; i += 1) {
_.memory.Free(options[i].longName);
_.memory.Free(options[i].description);
CleanParameters(options[i].required);
@ -318,110 +270,83 @@ protected function Finalizer()
commandData.options.length = 0;
}
private final function CleanParameters(array<Parameter> parameters)
{
private final function CleanParameters(array<Parameter> parameters) {
local int i;
for (i = 0; i < parameters.length; i += 1)
{
for (i = 0; i < parameters.length; i += 1) {
_.memory.Free(parameters[i].displayName);
_.memory.Free(parameters[i].variableName);
_.memory.Free(parameters[i].aliasSourceName);
}
}
/**
* Overload this method to use `builder` to define parameters and options for
* your command.
*
* @param builder Builder that can be used to define your commands parameters
* and options. Do not deallocate.
*/
/// Overload this method to use `builder` to define parameters and options for your command.
protected function BuildData(CommandDataBuilder builder){}
/**
* Overload this method to perform required actions when
* your command is called.
*
* @param arguments `struct` filled with parameters that your command
* has been called with. Guaranteed to not be in error state.
* @param instigator Player that instigated this execution.
*/
/// Overload this method to perform required actions when your command is called.
///
/// [`arguments`] is a `struct` filled with parameters that your command has been called with.
/// Guaranteed to not be in error state.
///
/// [`instigator`] is a player that instigated this execution.
protected function Executed(CallData arguments, EPlayer instigator){}
/**
* Overload this method to perform required actions when your command is called
* with a given player as a target. If several players have been specified -
* this method will be called once for each.
*
* If your command does not require a target - this method will not be called.
*
* @param target Player that this command must perform an action on.
* @param arguments `struct` filled with parameters that your command
* has been called with. Guaranteed to not be in error state and contain
* all the required data.
* @param instigator Player that instigated this call.
*/
protected function ExecutedFor(
EPlayer target,
CallData arguments,
EPlayer instigator){}
/**
* Returns an instance of command (of particular class) that is stored
* "as a singleton" in command's class itself. Do not deallocate it.
*/
public final static function Command GetInstance()
{
/// Overload this method to perform required actions when your command is called with a given player
/// as a target.
///
/// If several players have been specified - this method will be called once for each.
///
/// If your command does not require a target - this method will not be called.
///
/// [`target`] is a player that this command must perform an action on.
/// [`arguments`] is a `struct` filled with parameters that your command has been called with.
/// Guaranteed to not be in error state.
///
/// [`instigator`] is a player that instigated this execution.
protected function ExecutedFor(EPlayer target, CallData arguments, EPlayer instigator) {}
/// Returns an instance of command (of particular class) that is stored "as a singleton" in
/// command's class itself. Do not deallocate it.
public final static function Command GetInstance() {
if (default.mainInstance == none) {
default.mainInstance = Command(__().memory.Allocate(default.class));
}
return default.mainInstance;
}
/**
* Forces command to process (parse) player's input, producing a structure
* with parsed data in Acedia's format instead.
*
* @see `Execute()` for actually performing command's actions.
*
* @param parser Parser that contains command input.
* @param callerPlayer Player that initiated this command's call,
* necessary for parsing player list (since it can point at
* the caller player).
* @param subCommandName This method can optionally specify sub-command to
* caller command to use. If this argument's value is `none` - sub-command
* name will be parsed from the `parser`'s data.
* @return `CallData` structure that contains all the information about
* parameters specified in `parser`'s contents.
* Returned structure contains objects that must be deallocated,
* which can easily be done by the auxiliary `DeallocateCallData()` method.
*/
/// Forces command to process (parse) player's input, producing a structure with parsed data in
/// Acedia's format instead.
///
/// Use `Execute()` for actually performing command's actions.
///
/// [`subCommandName`] can be optionally specified to use as sub-command.
/// If this argument's value is `none` - sub-command name will be parsed from the `parser`'s data.
///
/// Returns `CallData` structure that contains all the information about parameters specified in
/// `parser`'s contents.
/// Returned structure contains objects that must be deallocated, which can easily be done by
/// the auxiliary `DeallocateCallData()` method.
public final function CallData ParseInputWith(
Parser parser,
EPlayer callerPlayer,
optional BaseText subCommandName)
{
optional BaseText subCommandName
) {
local array<EPlayer> targetPlayers;
local CommandParser commandParser;
local CallData callData;
if (parser == none || !parser.Ok())
{
if (parser == none || !parser.Ok()) {
callData.parsingError = CET_BadParser;
return callData;
}
// Parse targets and handle errors that can arise here
if (commandData.requiresTarget)
{
if (commandData.requiresTarget) {
targetPlayers = ParseTargets(parser, callerPlayer);
if (!parser.Ok())
{
if (!parser.Ok()) {
callData.parsingError = CET_IncorrectTargetList;
return callData;
}
if (targetPlayers.length <= 0)
{
if (targetPlayers.length <= 0) {
callData.parsingError = CET_EmptyTargetList;
return callData;
}
@ -438,24 +363,16 @@ public final function CallData ParseInputWith(
return callData;
}
/**
* Executes caller `Command` with data provided by `callData` if it is in
* a correct state and reports error to `callerPlayer` if
* `callData` is invalid.
*
* @param callData Data about parameters, options, etc. with which
* caller `Command` is to be executed.
* @param callerPlayer Player that should be considered responsible for
* executing this `Command`.
* @return `true` if command was successfully executed and `false` otherwise.
* Execution is considered successful if `Execute()` call was made,
* regardless of whether `Command` can actually perform required action.
* For example, giving a weapon to a player can fail because he does not
* have enough space in his inventory, but it will still be considered
* a successful execution as far as return value is concerned.
*/
public final function bool Execute(CallData callData, EPlayer callerPlayer)
{
/// Executes caller `Command` with data provided by `callData` if it is in a correct state and
/// reports error to `callerPlayer` if `callData` is invalid.
///
/// Returns `true` if command was successfully executed and `false` otherwise.
/// Execution is considered successful if `Execute()` call was made, regardless of whether `Command`
/// can actually perform required action.
/// For example, giving a weapon to a player can fail because he does not have enough space in his
/// inventory, but it will still be considered a successful execution as far as return value is
/// concerned.
public final function bool Execute(CallData callData, EPlayer callerPlayer) {
local int i;
local array<EPlayer> targetPlayers;
@ -463,8 +380,7 @@ public final function bool Execute(CallData callData, EPlayer callerPlayer)
if (!callerPlayer.IsExistent()) return false;
// Report or execute
if (callData.parsingError != CET_None)
{
if (callData.parsingError != CET_None) {
ReportError(callData, callerPlayer);
return false;
}
@ -479,10 +395,8 @@ public final function bool Execute(CallData callData, EPlayer callerPlayer)
othersConsole = _.console.ForAll().ButPlayer(callerPlayer);
Executed(callData, callerPlayer);
_.memory.Free(othersConsole);
if (commandData.requiresTarget)
{
for (i = 0; i < targetPlayers.length; i += 1)
{
if (commandData.requiresTarget) {
for (i = 0; i < targetPlayers.length; i += 1) {
targetConsole = _.console.For(targetPlayers[i]);
othersConsole = _.console
.ForAll()
@ -499,8 +413,7 @@ public final function bool Execute(CallData callData, EPlayer callerPlayer)
return true;
}
private final function DeallocateConsoles()
{
private final function DeallocateConsoles() {
if (publicConsole != none && publicConsole.IsAllocated()) {
_.memory.Free(publicConsole);
}
@ -519,16 +432,8 @@ private final function DeallocateConsoles()
othersConsole = none;
}
/**
* Auxiliary method that cleans up all data and deallocates all objects inside
* provided `callData` structure.
*
* @param callData Structure to clean. All stored data will be cleared,
* meaning that `DeallocateCallData()` method takes ownership of
* this parameter.
*/
public final static function DeallocateCallData(/* take */ CallData callData)
{
/// Auxiliary method that cleans up all data and deallocates all objects inside provided structure.
public final static function DeallocateCallData(/* take */ CallData callData) {
__().memory.Free(callData.subCommandName);
__().memory.Free(callData.parameters);
__().memory.Free(callData.options);
@ -541,8 +446,7 @@ public final static function DeallocateCallData(/* take */ CallData callData)
// Reports given error to the `callerPlayer`, appropriately picking
// message color
private final function ReportError(CallData callData, EPlayer callerPlayer)
{
private final function ReportError(CallData callData, EPlayer callerPlayer) {
local Text errorMessage;
local ConsoleWriter console;
@ -553,8 +457,7 @@ private final function ReportError(CallData callData, EPlayer callerPlayer)
console = callerPlayer.BorrowConsole();
if (callData.parsingError == CET_EmptyTargetList) {
console.UseColor(_.color.textWarning);
}
else {
} else {
console.UseColor(_.color.textFailure);
}
// Send message
@ -565,14 +468,12 @@ private final function ReportError(CallData callData, EPlayer callerPlayer)
console.ResetColor().Flush();
}
private final function Text PrintErrorMessage(CallData callData)
{
private final function Text PrintErrorMessage(CallData callData) {
local Text result;
local MutableText builder;
builder = _.text.Empty();
switch (callData.parsingError)
{
switch (callData.parsingError) {
case CET_BadParser:
builder.Append(P("Internal error occurred: invalid parser"));
break;
@ -580,26 +481,31 @@ private final function Text PrintErrorMessage(CallData callData)
builder.Append(P("Ill defined command: no subcommands"));
break;
case CET_BadSubCommand:
builder.Append(P("Ill defined sub-command: "))
builder
.Append(P("Ill defined sub-command: "))
.Append(callData.errorCause);
break;
case CET_NoRequiredParam:
builder.Append(P("Missing required parameter: "))
builder
.Append(P("Missing required parameter: "))
.Append(callData.errorCause);
break;
case CET_NoRequiredParamForOption:
builder.Append(P("Missing required parameter for option: "))
builder
.Append(P("Missing required parameter for option: "))
.Append(callData.errorCause);
break;
case CET_UnknownOption:
builder.Append(P("Invalid option specified: "))
builder
.Append(P("Invalid option specified: "))
.Append(callData.errorCause);
break;
case CET_UnknownShortOption:
builder.Append(P("Invalid short option specified"));
break;
case CET_RepeatedOption:
builder.Append(P("Option specified several times: "))
builder
.Append(P("Option specified several times: "))
.Append(callData.errorCause);
break;
case CET_UnusedCommandParameters:
@ -607,16 +513,18 @@ private final function Text PrintErrorMessage(CallData callData)
.Append(callData.errorCause);
break;
case CET_MultipleOptionsWithParams:
builder.Append(P( "Multiple short options in one declarations"
@ "require parameters: "))
builder
.Append(P("Multiple short options in one declarations require parameters: "))
.Append(callData.errorCause);
break;
case CET_IncorrectTargetList:
builder.Append(P("Target players are incorrectly specified."))
builder
.Append(P("Target players are incorrectly specified."))
.Append(callData.errorCause);
break;
case CET_EmptyTargetList:
builder.Append(P("List of target players is empty"))
builder
.Append(P("List of target players is empty"))
.Append(callData.errorCause);
break;
default:
@ -629,10 +537,7 @@ private final function Text PrintErrorMessage(CallData callData)
// Auxiliary method for parsing list of targeted players.
// Assumes given parser is not `none` and not in a failed state.
// If parsing failed, guaranteed to return an empty array.
private final function array<EPlayer> ParseTargets(
Parser parser,
EPlayer callerPlayer)
{
private final function array<EPlayer> ParseTargets(Parser parser, EPlayer callerPlayer) {
local array<EPlayer> targetPlayers;
local PlayersParser targetsParser;
@ -646,52 +551,35 @@ private final function array<EPlayer> ParseTargets(
return targetPlayers;
}
/**
* Returns name (in lower case) of the caller command class.
*
* @return Name (in lower case) of the caller command class.
* Guaranteed to be not `none`.
*/
public final function Text GetName()
{
/// Returns name (in lower case) of the caller command class.
public final function Text GetName() {
if (commandData.name == none) {
return P("").Copy();
}
return commandData.name.LowerCopy();
}
/**
* Returns group name (in lower case) of the caller command class.
*
* @return Group name (in lower case) of the caller command class.
* Guaranteed to be not `none`.
*/
public final function Text GetGroupName()
{
/// Returns group name (in lower case) of the caller command class.
public final function Text GetGroupName() {
if (commandData.group == none) {
return P("").Copy();
}
return commandData.group.LowerCopy();
}
/**
* Returns `Command.Data` struct that describes caller `Command`.
*
* @return `Command.Data` that describes caller `Command`. Returned struct
* contains `Text` references that are used internally by the `Command`
* and not their copies.
* Generally this is undesired approach and leaves `Command` more
* vulnerable to modification, but copying all the data inside would not
* only introduce a largely pointless computational overhead, but also
* would require some cumbersome logic. This might change in the future,
* so deallocating any objects in the returned `struct` would lead to
* undefined behavior.
*/
public final function Data BorrowData()
{
/// Returns `Command.Data` struct that describes caller `Command`.
///
/// Returned struct contains `Text` references that are used internally by the `Command` and
/// not their copies.
///
/// Generally this is undesired approach and leaves `Command` more vulnerable to modification,
/// but copying all the data inside would not only introduce a largely pointless computational
/// overhead, but also would require some cumbersome logic.
/// This might change in the future, so deallocating any objects in the returned `struct` would lead
/// to undefined behavior.
public final function Data BorrowData() {
return commandData;
}
defaultproperties
{
defaultproperties {
}

350
sources/BaseAPI/API/Commands/PlayersParser.uc
Unescape View File

@ -1,7 +1,8 @@
/**
* Object for parsing what converting textual description of a group of
* players into array of `EPlayer`s. Depends on the game context.
* Copyright 2021-2022 Anton Tarasenko
* Author: dkanus
* Home repo: https://www.insultplayers.ru/git/AcediaFramework/AcediaCore
* License: GPL
* Copyright 2021-2023 Anton Tarasenko
*------------------------------------------------------------------------------
* This file is part of Acedia.
*
@ -9,7 +10,7 @@
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 3 of the License, or
* (at your option) any later version.
*
*\
* Acedia is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
@ -21,67 +22,61 @@
class PlayersParser extends AcediaObject
dependson(Parser);
/**
* # `PlayersParser`
*
* This parser is supposed to parse player set definitions as they
* are used in commands.
* Basic use is to specify one of the selectors:
* 1. Key selector: "#<integer>" (examples: "#1", "#5").
* This one is used to specify players by their key, assigned to
* them when they enter the game. This type of selectors can be used
* when players have hard to type names.
* 2. Macro selector: "@self", "@me", "@all", "@admin" or just "@".
* "@", "@me", and "@self" are identical and can be used to
* specify player that called the command.
* "@admin" can be used to specify all admins in the game at once.
* "@all" specifies all current players.
* In future it is planned to make macros extendable by allowing to
* bind more names to specific groups of players.
* 3. Name selectors: quoted strings and any other types of string that
* do not start with either "#" or "@".
* These specify name prefixes: any player with specified prefix
* will be considered to match such selector.
*
* Negated selectors: "!<selector>". Specifying "!" in front of selector
* will select all players that do not match it instead.
*
* Grouped selectors: "['<selector1>', '<selector2>', ... '<selectorN>']".
* Specified selectors are process in order: from left to right.
* First selector works as usual and selects a set of players.
* All the following selectors either
* expand that list (additive ones, without "!" prefix)
* or remove specific players from the list (the ones with "!" prefix).
* Examples of that:
* *. "[@admin, !@self]" - selects all admins, except the one who called
* the command (whether he is admin or not).
* *. "[dkanus, 'mate']" - will select players "dkanus" and "mate".
* Order also matters, since:
* *. "[@admin, !@admin]" - won't select anyone, since it will first
* add all the admins and then remove them.
* *. "[!@admin, @admin]" - will select everyone, since it will first
* select everyone who is not an admin and then adds everyone else.
*
* ## Usage
*
* 1. Allocate `PlayerParser`;
* 2. Set caller player through `SetSelf()` method to make "@" and "@me"
* selectors usable;
* 3. Call `Parse()` or `ParseWith()` method with `BaseText`/`Parser` that
* starts with proper players selector;
* 4. Call `GetPlayers()` to obtain selected players array.
*
* ## Implementation
*
* When created, `PlayersParser` takes a snapshot (array) of current
* players on the server. Then `currentSelection` is decided based on whether
* first selector is positive (initial selection is taken as empty array) or
* negative (initial selection is taken as full snapshot).
* After that `PlayersParser` simply goes through specified selectors
* (in case more than one is specified) and adds or removes appropriate players
* in `currentSelection`, assuming that `playersSnapshot` is a current full
* array of players.
*/
//! This parser is supposed to parse player set definitions as they
//! are used in commands.
//!
//! Basic use is to specify one of the selectors:
//! 1. Key selector: "#<integer>" (examples: "#1", "#5").
//! This one is used to specify players by their key, assigned to them when they enter the game.
//! This type of selectors can be used when players have hard to type names.
//! 2. Macro selector: "@self", "@me", "@all", "@admin" or just "@".
//! "@", "@me", and "@self" are identical and can be used to specify player that called
//! the command.
//! "@admin" can be used to specify all admins in the game at once.
//! "@all" specifies all current players.
//! In future it is planned to make macros extendable by allowing to bind more names to specific
//! groups of players.
//! 3. Name selectors: quoted strings and any other types of string that do not start with
//! either "#" or "@".
//! These specify name prefixes: any player with specified prefix will be considered to match
//! such selector.
//!
//! Negated selectors: "!<selector>". Specifying "!" in front of selector will select all players
//! that do not match it instead.
//!
//! Grouped selectors: "['<selector1>', '<selector2>', ... '<selectorN>']".
//! Specified selectors are process in order: from left to right.
//! First selector works as usual and selects a set of players.
//! All the following selectors either expand that list (additive ones, without "!" prefix) or
//! remove specific players from the list (the ones with "!" prefix).
//! Examples of that:
//!
//! * "[@admin, !@self]" - selects all admins, except the one who called the command
//! (whether he is admin or not).
//! * "[dkanus, 'mate']" - will select players "dkanus" and "mate". Order also matters, since:
//! * "[@admin, !@admin]" - won't select anyone, since it will first add all the admins and
//! then remove them.
//! * "[!@admin, @admin]" - will select everyone, since it will first select everyone who is
//! not an admin and then adds everyone else.
//!
//! # Usage
//!
//! 1. Allocate `PlayerParser`;
//! 2. Set caller player through `SetSelf()` method to make "@" and "@me" selectors usable;
//! 3. Call `Parse()` or `ParseWith()` method with `BaseText`/`Parser` that starts with proper
//! players selector;
//! 4. Call `GetPlayers()` to obtain selected players array.
//!
//! # Implementation
//!
//! When created, `PlayersParser` takes a snapshot (array) of current players on the server.
//! Then `currentSelection` is decided based on whether first selector is positive
//! (initial selection is taken as empty array) or negative
//! (initial selection is taken as full snapshot).
//!
//! After that `PlayersParser` simply goes through specified selectors
//! (in case more than one is specified) and adds or removes appropriate players in
//! `currentSelection`, assuming that `playersSnapshot` is a current full array of players.
// Player for which "@", "@me", and "@self" macros will refer
var private EPlayer selfPlayer;
@ -101,8 +96,7 @@ var private array<Text> selectorDelimiters;
var const int TSELF, TME, TADMIN, TALL, TNOT, TKEY, TMACRO, TCOMMA;
var const int TOPEN_BRACKET, TCLOSE_BRACKET;
protected function Finalizer()
{
protected function Finalizer() {
// No need to deallocate `currentSelection`,
// since it has `EPlayer`s from `playersSnapshot` or `selfPlayer`
_.memory.Free(selfPlayer);
@ -113,15 +107,10 @@ protected function Finalizer()
currentSelection.length = 0;
}
/**
* Set a player who will be referred to by "@", "@me" and "@self" macros.
*
* @param newSelfPlayer Player who will be referred to by "@", "@me" and
* "@self" macros. Passing `none` will make it so no one is
* referred by them.
*/
public final function SetSelf(EPlayer newSelfPlayer)
{
/// Set a player who will be referred to by "@", "@me" and "@self" macros.
///
/// Passing `none` will make it so no one is referred by these macros.
public final function SetSelf(EPlayer newSelfPlayer) {
_.memory.Free(selfPlayer);
selfPlayer = none;
if (newSelfPlayer != none) {
@ -129,18 +118,17 @@ public final function SetSelf(EPlayer newSelfPlayer)
}
}
// Insert a new player into currently selected list of players
// (`currentSelection`) such that there will be no duplicates.
// Insert a new player into currently selected list of players (`currentSelection`) such that there
// will be no duplicates.
//
// `none` values are auto-discarded.
private final function InsertPlayer(EPlayer toInsert)
{
private final function InsertPlayer(EPlayer toInsert) {
local int i;
if (toInsert == none) {
return;
}
for (i = 0; i < currentSelection.length; i += 1)
{
for (i = 0; i < currentSelection.length; i += 1) {
if (currentSelection[i] == toInsert) {
return;
}
@ -149,12 +137,10 @@ private final function InsertPlayer(EPlayer toInsert)
}
// Adds all the players with specified key (`key`) to the current selection.
private final function AddByKey(int key)
{
private final function AddByKey(int key) {
local int i;
for (i = 0; i < playersSnapshot.length; i += 1)
{
for (i = 0; i < playersSnapshot.length; i += 1) {
if (playersSnapshot[i].GetIdentity().GetKey() == key) {
InsertPlayer(playersSnapshot[i]);
}
@ -163,32 +149,27 @@ private final function AddByKey(int key)
// Removes all the players with specified key (`key`) from
// the current selection.
private final function RemoveByKey(int key)
{
private final function RemoveByKey(int key) {
local int i;
while (i < currentSelection.length)
{
while (i < currentSelection.length) {
if (currentSelection[i].GetIdentity().GetKey() == key) {
currentSelection.Remove(i, 1);
}
else {
} else {
i += 1;
}
}
}
// Adds all the players with specified name (`name`) to the current selection.
private final function AddByName(BaseText name)
{
private final function AddByName(BaseText name) {
local int i;
local Text nextPlayerName;
if (name == none) {
return;
}
for (i = 0; i < playersSnapshot.length; i += 1)
{
for (i = 0; i < playersSnapshot.length; i += 1) {
nextPlayerName = playersSnapshot[i].GetName();
if (nextPlayerName.StartsWith(name, SCASE_INSENSITIVE)) {
InsertPlayer(playersSnapshot[i]);
@ -199,18 +180,15 @@ private final function AddByName(BaseText name)
// Removes all the players with specified name (`name`) from
// the current selection.
private final function RemoveByName(BaseText name)
{
private final function RemoveByName(BaseText name) {
local int i;
local Text nextPlayerName;
while (i < currentSelection.length)
{
while (i < currentSelection.length) {
nextPlayerName = currentSelection[i].GetName();
if (nextPlayerName.StartsWith(name, SCASE_INSENSITIVE)) {
currentSelection.Remove(i, 1);
}
else {
} else {
i += 1;
}
nextPlayerName.FreeSelf();
@ -218,12 +196,10 @@ private final function RemoveByName(BaseText name)
}
// Adds all the admins to the current selection.
private final function AddAdmins()
{
private final function AddAdmins() {
local int i;
for (i = 0; i < playersSnapshot.length; i += 1)
{
for (i = 0; i < playersSnapshot.length; i += 1) {
if (playersSnapshot[i].IsAdmin()) {
InsertPlayer(playersSnapshot[i]);
}
@ -231,16 +207,13 @@ private final function AddAdmins()
}
// Removes all the admins from the current selection.
private final function RemoveAdmins()
{
private final function RemoveAdmins() {
local int i;
while (i < currentSelection.length)
{
while (i < currentSelection.length) {
if (currentSelection[i].IsAdmin()) {
currentSelection.Remove(i, 1);
}
else {
} else {
i += 1;
}
}
@ -248,61 +221,48 @@ private final function RemoveAdmins()
// Add all the players specified by `macroText` (from macro "@<macroText>").
// Does nothing if there is no such macro.
private final function AddByMacro(BaseText macroText)
{
if (macroText.Compare(T(TADMIN), SCASE_INSENSITIVE))
{
private final function AddByMacro(BaseText macroText) {
if (macroText.Compare(T(TADMIN), SCASE_INSENSITIVE)) {
AddAdmins();
return;
}
if (macroText.Compare(T(TALL), SCASE_INSENSITIVE))
{
if (macroText.Compare(T(TALL), SCASE_INSENSITIVE)) {
currentSelection = playersSnapshot;
return;
}
if ( macroText.IsEmpty()
|| macroText.Compare(T(TSELF), SCASE_INSENSITIVE)
|| macroText.Compare(T(TME), SCASE_INSENSITIVE))
{
|| macroText.Compare(T(TME), SCASE_INSENSITIVE)) {
InsertPlayer(selfPlayer);
}
}
// Removes all the players specified by `macroText`
// (from macro "@<macroText>").
// Removes all the players specified by `macroText` (from macro "@<macroText>").
// Does nothing if there is no such macro.
private final function RemoveByMacro(BaseText macroText)
{
private final function RemoveByMacro(BaseText macroText) {
local int i;
if (macroText.Compare(T(TADMIN), SCASE_INSENSITIVE))
{
if (macroText.Compare(T(TADMIN), SCASE_INSENSITIVE)) {
RemoveAdmins();
return;
}
if (macroText.Compare(T(TALL), SCASE_INSENSITIVE))
{
if (macroText.Compare(T(TALL), SCASE_INSENSITIVE)) {
currentSelection.length = 0;
return;
}
if (macroText.IsEmpty() || macroText.Compare(T(TSELF), SCASE_INSENSITIVE))
{
while (i < currentSelection.length)
{
if (macroText.IsEmpty() || macroText.Compare(T(TSELF), SCASE_INSENSITIVE)) {
while (i < currentSelection.length) {
if (currentSelection[i] == selfPlayer) {
currentSelection.Remove(i, 1);
}
else {
} else {
i += 1;
}
}
}
}
// Parses one selector from `parser`, while accordingly modifying current
// player selection list.
private final function ParseSelector(Parser parser)
{
// Parses one selector from `parser`, while accordingly modifying current player selection list.
private final function ParseSelector(Parser parser) {
local bool additiveSelector;
local Parser.ParserState confirmedState;
@ -310,14 +270,12 @@ private final function ParseSelector(Parser parser)
if (!parser.Ok()) return;
confirmedState = parser.GetCurrentState();
if (!parser.Match(T(TNOT)).Ok())
{
if (!parser.Match(T(TNOT)).Ok()) {
additiveSelector = true;
parser.RestoreState(confirmedState);
}
// Determine whether we stars with empty or full player list
if (!parsedFirstSelector)
{
if (!parsedFirstSelector) {
parsedFirstSelector = true;
if (additiveSelector) {
currentSelection.length = 0;
@ -328,14 +286,12 @@ private final function ParseSelector(Parser parser)
}
// Try all selector types
confirmedState = parser.GetCurrentState();
if (parser.Match(T(TKEY)).Ok())
{
if (parser.Match(T(TKEY)).Ok()) {
ParseKeySelector(parser, additiveSelector);
return;
}
parser.RestoreState(confirmedState);
if (parser.Match(T(TMACRO)).Ok())
{
if (parser.Match(T(TMACRO)).Ok()) {
ParseMacroSelector(parser, additiveSelector);
return;
}
@ -343,10 +299,9 @@ private final function ParseSelector(Parser parser)
ParseNameSelector(parser, additiveSelector);
}
// Parse key selector (assuming "#" is already consumed), while accordingly
// modifying current player selection list.
private final function ParseKeySelector(Parser parser, bool additiveSelector)
{
// Parse key selector (assuming "#" is already consumed), while accordingly modifying current player
// selection list.
private final function ParseKeySelector(Parser parser, bool additiveSelector) {
local int key;
if (parser == none) return;
@ -355,16 +310,14 @@ private final function ParseKeySelector(Parser parser, bool additiveSelector)
if (additiveSelector) {
AddByKey(key);
}
else {
} else {
RemoveByKey(key);
}
}
// Parse macro selector (assuming "@" is already consumed), while accordingly
// modifying current player selection list.
private final function ParseMacroSelector(Parser parser, bool additiveSelector)
{
// Parse macro selector (assuming "@" is already consumed), while accordingly modifying current
// player selection list.
private final function ParseMacroSelector(Parser parser, bool additiveSelector) {
local MutableText macroName;
local Parser.ParserState confirmedState;
@ -373,8 +326,7 @@ private final function ParseMacroSelector(Parser parser, bool additiveSelector)
confirmedState = parser.GetCurrentState();
macroName = ParseLiteral(parser);
if (!parser.Ok())
{
if (!parser.Ok()) {
_.memory.Free(macroName);
return;
}
@ -387,10 +339,8 @@ private final function ParseMacroSelector(Parser parser, bool additiveSelector)
_.memory.Free(macroName);
}
// Parse name selector, while accordingly modifying current player
// selection list.
private final function ParseNameSelector(Parser parser, bool additiveSelector)
{
// Parse name selector, while accordingly modifying current player selection list.
private final function ParseNameSelector(Parser parser, bool additiveSelector) {
local MutableText playerName;
local Parser.ParserState confirmedState;
@ -399,8 +349,7 @@ private final function ParseNameSelector(Parser parser, bool additiveSelector)
confirmedState = parser.GetCurrentState();
playerName = ParseLiteral(parser);
if (!parser.Ok() || playerName.IsEmpty())
{
if (!parser.Ok() || playerName.IsEmpty()) {
_.memory.Free(playerName);
return;
}
@ -413,12 +362,11 @@ private final function ParseNameSelector(Parser parser, bool additiveSelector)
_.memory.Free(playerName);
}
// Reads a string that can either be a body of name selector
// (some player's name prefix) or of a macro selector (what comes after "@").
// This is different from `parser.MString()` because it also uses
// "," as a separator.
private final function MutableText ParseLiteral(Parser parser)
{
// Reads a string that can either be a body of name selector (some player's name prefix) or
// of a macro selector (what comes after "@").
//
// This is different from `parser.MString()` because it also uses "," as a separator.
private final function MutableText ParseLiteral(Parser parser) {
local MutableText literal;
local Parser.ParserState confirmedState;
@ -426,27 +374,21 @@ private final function MutableText ParseLiteral(Parser parser)
if (!parser.Ok()) return none;
confirmedState = parser.GetCurrentState();
if (!parser.MStringLiteral(literal).Ok())
{
if (!parser.MStringLiteral(literal).Ok()) {
parser.RestoreState(confirmedState);
parser.MUntilMany(literal, selectorDelimiters, true);
}
return literal;
}
/**
* Returns players parsed by the last `ParseWith()` or `Parse()` call.
* If neither were yet called - returns an empty array.
*
* @return players parsed by the last `ParseWith()` or `Parse()` call.
*/
public final function array<EPlayer> GetPlayers()
{
/// Returns players parsed by the last `ParseWith()` or `Parse()` call.
///
/// If neither were yet called - returns an empty array.
public final function array<EPlayer> GetPlayers() {
local int i;
local array<EPlayer> result;
for (i = 0; i < currentSelection.length; i += 1)
{
for (i = 0; i < currentSelection.length; i += 1) {
if (currentSelection[i].IsExistent()) {
result[result.length] = EPlayer(currentSelection[i].Copy());
}
@ -454,17 +396,12 @@ public final function array<EPlayer> GetPlayers()
return result;
}
/**
* Parses players from `parser` according to the currently present players.
*
* Array of parsed players can be retrieved by `self.GetPlayers()` method.
*
* @param parser `Parser` from which to parse player list.
* It's state will be set to failed in case the parsing fails.
* @return `true` if parsing was successful and `false` otherwise.
*/
public final function bool ParseWith(Parser parser)
{
/// Parses players from `parser` according to the currently present players.
///
/// Array of parsed players can be retrieved by `self.GetPlayers()` method.
///
/// Returns `true` if parsing was successful and `false` otherwise.
public final function bool ParseWith(Parser parser) {
local Parser.ParserState confirmedState;
if (parser == none) return false;
@ -473,16 +410,14 @@ public final function bool ParseWith(Parser parser)
Reset();
confirmedState = parser.Skip().GetCurrentState();
if (!parser.Match(T(TOPEN_BRACKET)).Ok())
{
if (!parser.Match(T(TOPEN_BRACKET)).Ok()) {
ParseSelector(parser.RestoreState(confirmedState));
if (parser.Ok()) {
return true;
}
return false;
}
while (parser.Ok() && !parser.HasFinished())
{
while (parser.Ok() && !parser.HasFinished()) {
confirmedState = parser.Skip().GetCurrentState();
if (parser.Match(T(TCLOSE_BRACKET)).Ok()) {
return true;
@ -500,8 +435,7 @@ public final function bool ParseWith(Parser parser)
// Resets this object to initial state before parsing and update
// `playersSnapshot` to contain current players.
private final function Reset()
{
private final function Reset() {
parsedFirstSelector = false;
currentSelection.length = 0;
_.memory.FreeMany(playersSnapshot);
@ -512,16 +446,11 @@ private final function Reset()
selectorDelimiters[1] = T(TCLOSE_BRACKET);
}
/**
* Parses players from `toParse` according to the currently present players.
*
* Array of parsed players can be retrieved by `self.GetPlayers()` method.
*
* @param toParse `Text` from which to parse player list.
* @return `true` if parsing was successful and `false` otherwise.
*/
public final function bool Parse(BaseText toParse)
{
/// Parses players from according to the currently present players.
///
/// Array of parsed players can be retrieved by `self.GetPlayers()` method.
/// Returns `true` if parsing was successful and `false` otherwise.
public final function bool Parse(BaseText toParse) {
local bool wasSuccessful;
local Parser parser;
@ -534,8 +463,7 @@ public final function bool Parse(BaseText toParse)
return wasSuccessful;
}
defaultproperties
{
defaultproperties {
TSELF = 0
stringConstants(0) = "self"
TADMIN = 1

Write Preview
Loading…
Cancel
Save