// Copyright 2011-2022 David Robillard <d@drobilla.net>
// SPDX-License-Identifier: ISC

#ifndef SERD_WRITER_H
#define SERD_WRITER_H

#include "serd/attributes.h"
#include "serd/env.h"
#include "serd/output_stream.h"
#include "serd/sink.h"
#include "serd/status.h"
#include "serd/string_view.h"
#include "serd/syntax.h"
#include "serd/world.h"
#include "zix/attributes.h"

#include <stddef.h>
#include <stdint.h>

SERD_BEGIN_DECLS

/**
   @defgroup serd_writer Writer
   @ingroup serd_reading_writing
   @{
*/

/// Streaming serialiser that writes a text stream as statements are pushed
typedef struct SerdWriterImpl SerdWriter;

/**
   Writer style options.

   These flags allow more precise control of writer output style.  Note that
   some options are only supported for some syntaxes, for example, NTriples
   does not support abbreviation and is always ASCII.
*/
typedef enum {
  SERD_WRITE_ASCII       = 1U << 0U, ///< Escape all non-ASCII characters
  SERD_WRITE_UNQUALIFIED = 1U << 1U, ///< Do not shorten URIs into CURIEs
  SERD_WRITE_UNRESOLVED  = 1U << 2U, ///< Do not make URIs relative
  SERD_WRITE_LAX         = 1U << 3U, ///< Tolerate lossy output
  SERD_WRITE_TERSE       = 1U << 4U, ///< Write terser output without newlines
} SerdWriterFlag;

/// Bitwise OR of #SerdWriterFlag values
typedef uint32_t SerdWriterFlags;

/// Create a new RDF writer
SERD_API SerdWriter* ZIX_ALLOCATED
serd_writer_new(SerdWorld* ZIX_NONNULL        world,
                SerdSyntax                    syntax,
                SerdWriterFlags               flags,
                const SerdEnv* ZIX_NONNULL    env,
                SerdOutputStream* ZIX_NONNULL output,
                size_t                        block_size);

/// Free `writer`
SERD_API void
serd_writer_free(SerdWriter* ZIX_NULLABLE writer);

/// Return a sink interface that emits statements via `writer`
SERD_CONST_API const SerdSink* ZIX_NONNULL
serd_writer_sink(SerdWriter* ZIX_NONNULL writer);

/**
   Set a prefix to be removed from matching blank node identifiers.

   This is the counterpart to serd_reader_add_blank_prefix() which can be used
   to "undo" added prefixes.
*/
SERD_API void
serd_writer_chop_blank_prefix(SerdWriter* ZIX_NONNULL  writer,
                              const char* ZIX_NULLABLE prefix);

/**
   Set the current root URI.

   The root URI should be a prefix of the base URI.  The path of the root URI
   is the highest path any relative up-reference can refer to.  For example,
   with root <file:///foo/root> and base <file:///foo/root/base>,
   <file:///foo/root> will be written as <../>, but <file:///foo> will be
   written non-relatively as <file:///foo>.  If the root is not explicitly set,
   it defaults to the base URI, so no up-references will be created at all.
*/
SERD_API SerdStatus
serd_writer_set_root_uri(SerdWriter* ZIX_NONNULL writer, SerdStringView uri);

/**
   Finish a write.

   This flushes any pending output, for example terminating punctuation, so
   that the output is a complete document.
*/
SERD_API SerdStatus
serd_writer_finish(SerdWriter* ZIX_NONNULL writer);

/**
   @}
*/

SERD_END_DECLS

#endif // SERD_WRITER_H