/*
 * Copyright (C) Birb Developers
 *
 * Birb is the legal property of its developers, whose names are too numerous
 * to list here. Please refer to the AUTHORS 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 Lesser General Public License as published by the
 * Free Software Foundation; either version 2.1 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 Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(BIRB_GLOBAL_HEADER_INSIDE) && !defined(BIRB_COMPILATION)
# error "only <birb.h> may be included directly"
#endif

#ifndef BIRB_READLINE_H
#define BIRB_READLINE_H

#include <gio/gio.h>

#include "birbversion.h"

G_BEGIN_DECLS

#define BIRB_TYPE_READLINE (birb_readline_get_type())

/**
 * BirbReadline:
 *
 * A [GNU Readline](https://en.wikipedia.org/wiki/GNU_Readline) like
 * implementation.
 *
 * A [class@Readline] can be created with [ctor@Readline.new]. Calling
 * [method@Readline.read_stdin_async] or [method@Readline.read_stream_async]
 * will read input from the stream until a new-line `\n` is found. When the
 * new-line is found, the callback will be called and
 * [method@Readline.read_stream_finish] should be called to get the result.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
G_DECLARE_FINAL_TYPE(BirbReadline, birb_readline, BIRB, READLINE, GObject)

/**
 * birb_readline_get_line:
 *
 * Gets the line that the user has entered so far.
 *
 * Returns: The current input.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
const char *birb_readline_get_line(BirbReadline *readline);

/**
 * birb_readline_get_prompt:
 *
 * Gets the prompt from @readline.
 *
 * Returns: (nullable): The prompt.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
const char *birb_readline_get_prompt(BirbReadline *readline);

/**
 * birb_readline_new:
 * @prompt: (nullable): the prompt to display
 *
 * Creates a new readline with the given prompt.
 *
 * Returns: (transfer full): The new readline.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
BirbReadline *birb_readline_new(const char *prompt);

/**
 * birb_readline_set_prompt:
 * @prompt: (nullable): the new prompt
 *
 * Sets the prompt of @readline to @prompt.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
void birb_readline_set_prompt(BirbReadline *readline, const char *prompt);

/**
 * birb_readline_read_stdin_async: (finish-func birb_readline_read_stream_finish):
 * @cancellable: (nullable): an optional cancellable
 * @callback: (nullable): an optional callback
 * @data: the user data to pass to the callback
 *
 * Calls [method@Readline.read_stream_async] with `STDIN` as the stream.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
void birb_readline_read_stdin_async(BirbReadline *readline, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer data);

/**
 * birb_readline_read_stream_async:
 * @input: (transfer none): the input stream to read
 * @cancellable: (nullable): an optional cancellable
 * @callback: (nullable): an optional callback
 * @data: the user data to pass to the callback
 *
 * Reads a line of text from the given stream.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
void birb_readline_read_stream_async(BirbReadline *readline, GInputStream *input, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer data);

/**
 * birb_readline_read_stream_finish:
 * @result: the result
 * @error: (out) (nullable): a return address for a #GError
 *
 * Gets the line that was read.
 *
 * Returns: (transfer full) (nullable): The line that was read.
 *
 * Since: 0.9
 */
BIRB_AVAILABLE_IN_0_9
char *birb_readline_read_stream_finish(BirbReadline *readline, GAsyncResult *result, GError **error);

G_END_DECLS

#endif /* BIRB_READLINE_H */
