nstg/lib/trl.d.ts

Sends telegrams to a list of NationStates nations defined using a powerful query language called Telegram Recipient Language

/**
 * Copyright (C) 2016-2017 Auralia
 *
 * 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.
 */
import { NsApi } from "nsapi";
import { RefreshOverrideCache } from "./api";
/**
 * Represents a directive to the TRL evaluator to take a particular action
 * with respect to a specified set of nations with respect to the nations
 * currently in that group.
 */
export interface RecipientCommand {
    /**
     * The action to take with respect to the specified nations.
     */
    action: Action;
    /**
     * The specified nations, given as a primitive or as a group.
     */
    recipients: RecipientPrimitive | RecipientCommand[];
    /**
     * A set of one-based indices that identify the location of the command
     * within the TRL string.
     *
     * For example, if the TRL string was "a; (b; c; (d; e;););", then the
     * position of command "a" is [1] while the position of command "e" is
     * [2, 3, 2].
     */
    position: number[];
}
/**
 * Represents a set of nations that meet some criteria defined by a specified
 * category and associated arguments.
 */
export interface RecipientPrimitive {
    /**
     * The category of the primitive.
     */
    category: string;
    /**
     * The category arguments of the primitive.
     */
    args: string[];
}
/**
 * Represents the action associated with a recipient command.
 */
export declare enum Action {
    /**
     * Add the recipients to the current group.
     */
    Add = 1,
    /**
     * Remove the recipients from the current group.
     */
    Remove = 2,
    /**
     * Remove all recipients from the current group that are not in this
     * list of recipients.
     */
    Limit = 3,
}
/**
 * Error thrown during TRL parsing.
 */
export declare class ParseError extends Error {
    /**
     * The message associated with the error.
     */
    message: string;
    /**
     * A set of one-based indices that identify the location of the command
     * that caused the error within the original TRL string.
     *
     * For example, if the TRL string was "a; (b; c; (d; e;););", then
     * [2, 3, 2] indicates that command "e" caused the error.
     */
    position: number[];
    /**
     * Initializes a new instance of the ParseError class.
     *
     * @param message The message associated with the error.
     * @param position A set of one-based indices that identify the location of
     *                 the command that caused the error within the original
     *                 TRL string.
     */
    constructor(message: string, position: number[]);
}
/**
 * Parses and evaluates a TRL string using the specified API.
 *
 * @param api The specified API.
 * @param trl The specified TRL string.
 * @param refreshOverrideCache Rules for when to override API caching when
 *                             re-evaluating a TRL string in continuous mode.
 *
 * @return A promise returning the nations represented by the specified TRL
 *         string.
 */
export declare function getRecipients(api: NsApi, trl: string, refreshOverrideCache?: RefreshOverrideCache): Promise<string[]>;
/**
 * Throws an error if the specified TRL string is not valid.
 */
export declare function validateTrl(trl: string): void;
/**
 * Evaluates the specified recipient commands using the specified API.
 *
 * @param api The specified API.
 * @param commands The specified recipient commands.
 * @param refreshOverrideCache Rules for when to override API caching when
 *                             re-evaluating a TRL string in continuous mode.
 *
 * @return A promise returning the list of nations that the specified TRL string
 *         evaluates to.
 */
export declare function evaluateTrl(api: NsApi, commands: RecipientCommand[], refreshOverrideCache: RefreshOverrideCache): Promise<string[]>;