libpurple/purplecommandmanager.h

/*
 * Purple - Internet Messaging Library
 * Copyright (C) Pidgin Developers <devel@pidgin.im>
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here. Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your option)
 * any later version.
 *
 * This library 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 GNU General Public License for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this library; if not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#endif

#ifndef PURPLE_COMMAND_MANAGER_H
#define PURPLE_COMMAND_MANAGER_H

#include <glib.h>
#include <glib-object.h>

#include "purplecommand.h"
#include "purpleconversation.h"
#include "purpleversion.h"

G_BEGIN_DECLS

/**
 * PurpleCommandManager:
 *
 * A manager of [class@Command] objects.
 *
 * libpurple, user interfaces, and plugins can manage the commands that are
 * available with [method@CommandManager.add] and
 * [method@CommandManager.remove].
 *
 * User interfaces can use [method@CommandManager.find_and_execute] to quickly
 * find and execute a command. They can also use
 * [method@CommandManager.find_all] to get a list of all commands which can be
 * presented to a user.
 *
 * Both [method@CommandManager.find] and [method@CommandManager.find_all] take
 * an optional [class@Conversation] parameter. If it is not %NULL, its
 * [property@Conversation:tags] property will be searched with
 * [method@Tags.contains] using the [property@Command:tags] as the needle to
 * determine which commands are available for the [class@Conversation].
 *
 * When plugins are being unloaded, they should call
 * [method@CommandManager.remove_all_with_source] to remove their commands.
 *
 * Since: 3.0
 */

#define PURPLE_TYPE_COMMAND_MANAGER (purple_command_manager_get_type())

PURPLE_AVAILABLE_IN_3_0
G_DECLARE_FINAL_TYPE(PurpleCommandManager, purple_command_manager, PURPLE,
                     COMMAND_MANAGER, GObject)

/**
 * purple_command_manager_add:
 * @manager: The instance.
 * @command: (transfer full): The new command to add.
 *
 * Adds @command to @manager.
 *
 * If @manager already has a command with a matching name and source, @command
 * will not be added but ownership will still be taken.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_manager_add(PurpleCommandManager *manager, PurpleCommand *command);

/**
 * purple_command_manager_find:
 * @manager: The instance.
 * @conversation: (nullable): An optional conversation.
 * @name: The name of the command.
 *
 * Finds the command with a name of @name with the highest priority.
 *
 * If @conversation is not %NULL commands will be filtered to only include
 * those that are valid for @conversation by using [method@Tags.contains] on
 * @conversation with the tags of the found commands.
 *
 * Returns: (transfer none): The command if found, otherwise %NULL.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleCommand *purple_command_manager_find(PurpleCommandManager *manager, PurpleConversation *conversation, const char *name);

/**
 * purple_command_manager_find_all:
 * @manager: The instance.
 * @conversation: (nullable): An optional conversation.
 * @name: The name of the command.
 *
 * Finds all commands that match @name in @manager.
 *
 * If @conversation is not %NULL, [method@Tags.contains] will be used to filter
 * out commands whose tags don't match @conversation.
 *
 * Returns: (transfer full): The list of found plugins which could be empty.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
GListModel *purple_command_manager_find_all(PurpleCommandManager *manager, PurpleConversation *conversation, const char *name);

/**
 * purple_command_manager_find_and_execute:
 * @manager: The instance.
 * @conversation: The conversation to use.
 * @command_line: The command line including the name and arguments.
 *
 * Attempts to find a [class@Command] in @manager and execute it.
 *
 * @command_line should be a space separate string of the command name and any
 * arguments. It should not include a leading `/` or any other prefix.
 *
 * This method is a helper around [method@CommandManager.find] and
 * [method@Command.execute].
 *
 * Returns: %TRUE if a command was found and executed, otherwise %FALSE.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_command_manager_find_and_execute(PurpleCommandManager *manager, PurpleConversation *conversation, const char *command_line);

/**
 * purple_command_manager_get_commands_for_conversation:
 * @manager: The instance.
 * @conversation: The conversation.
 *
 * Gets a list of [class@Command]'s that are available for @conversation.
 *
 * Internally this filters the list of commands with [method@Tags.contains] to
 * check that all of [property@Command:tags] are contained in
 * [property@Conversation:tags].
 *
 * Returns: (transfer full): The list of commands, which may be empty.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
GListModel *purple_command_manager_get_commands_for_conversation(PurpleCommandManager *manager, PurpleConversation *conversation);

/**
 * purple_command_manager_get_default:
 *
 * Gets the default instance that libpurple is using.
 *
 * Returns: (transfer none): The instance.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleCommandManager *purple_command_manager_get_default(void);

/**
 * purple_command_manager_get_default_as_model:
 *
 * Gets the default instance of the manager but cast to [iface@Gio.ListModel].
 *
 * Returns: (transfer none): The manager cast as a [iface@Gio.ListModel].
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
GListModel *purple_command_manager_get_default_as_model(void);

/**
 * purple_command_manager_new:
 *
 * Creates a new instance.
 *
 * This is typically only used by libpurple but you can get the default
 * instance that libpurple is using with [func@CommandManager.get_default].
 *
 * Returns: (transfer full): The new instance.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleCommandManager *purple_command_manager_new(void);

/**
 * purple_command_manager_remove:
 * @manager: The instance.
 * @name: The name of the command.
 * @source: The source of the command.
 *
 * Attempts to remove the first command with @name and @source from @manager.
 *
 * Returns: %TRUE if a command is found and removed, otherwise %FALSE.
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_command_manager_remove(PurpleCommandManager *manager, const char *name, const char *source);

/**
 * purple_command_manager_remove_all_with_source:
 * @manager: The instance.
 * @source: The source whose commands to remove.
 *
 * Removes all commands from @manager that have a source of @source.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_manager_remove_all_with_source(PurpleCommandManager *manager, const char *source);

G_END_DECLS

#endif /* PURPLE_COMMAND_MANAGER_H */