<commit_before>#ifndef _LIBDISIR_IO_H
#define _LIBDISIR_IO_H

#ifdef __cplusplus
extern "C"{
#endif // _cplusplus


//! Disir Entry - holds information about single config/mold entries.
struct disir_entry
{
    //! Name of this entry.
    char                *de_entry_name;
    union
    {
        uint64_t        de_attributes;
        struct
        {
                        //! Entry is readbale by the user who queried this entry.
            uint64_t    DE_READABLE                 : 1,
                        //! Entry is writable by the user who queried this entry.
                        DE_WRITABLE                 : 1,
                        //! Entry is valid for all subentries of this namespace.
                        DE_NAMESPACE_ENTRY          : 1,
                                                    : 0;
        };
    };

    //! Double-linked list pointers.
    struct disir_entry *next, *prev;
};


//! \brief Free a entry structure returned from a I/O API.
//!
//! \return DISIR_STATUS_OK
enum disir_status
disir_entry_finished (struct disir_entry **entry);

//! \brief Input a config entry from the disir instance.
//!
//! Read a Config object from `disir` identified by ID `entry_id`.
//! The `mold` argument may optionally override the internal mold associated
//! wth `entry_id`. If supplied, it is the callers responsibility to invoke disir_mold_finished()
//! on this instance. Normally, this argument should be NULL.
//!
//! \param[in] instance Library instance.
//! \param[in] group_id String identifier for the which group to look for entry.
//! \param[in] entry_id String identifier for the config entry to read.
//! \param[in] mold Optional mold that describes the config to parse. If NULL,
//!     I/O plugin must locate a mold instead.
//! \param[out] config Object to populate with the state read from 'id'
//!
//! \return DISIR_STATUS_INVALID_ARGUMENT if either of arguments `disir`,
//      `entry_id` or `config` are NULL.
//! \return DISIR_STATUS_NO_CAN_DO if the matching plugin
//!     for some reason does not implement config_write operation.
//! \return DISIR_STATUS_NOT_EXIST if the plugin associated with `config`
//!     is not registered with `disir`.
//! \return status of the plugin config_read operation.
//!
enum disir_status
disir_config_read (struct disir_instance *instance, const char *group_id, const char *entry_id,
                   struct disir_mold *mold, struct disir_config **config);

//! \brief Output the config object to the disir instance.
//!
//! \param[in] instance Library instance.
//! \param[in] group_id String identifier for the which group to look for entry.
//! \param[in] entry_id String identifier for output location.
//! \param[in] config The config object to output.
//!
//! \return DISIR_STATUS_INVALID_ARGUMENT if either of the input arguments are NULL.
//! \return DISIR_STATUS_NO_CAN_DO if the `config` object is not associated with a plugin.
//! \return DISIR_STATUS_NO_CAN_DO if the matching plugin<commit_msg>doc lib: update disir_config_read docstring<commit_after>#ifndef _LIBDISIR_IO_H
#define _LIBDISIR_IO_H

#ifdef __cplusplus
extern "C"{
#endif // _cplusplus


//! Disir Entry - holds information about single config/mold entries.
struct disir_entry
{
    //! Name of this entry.
    char                *de_entry_name;
    union
    {
        uint64_t        de_attributes;
        struct
        {
                        //! Entry is readbale by the user who queried this entry.
            uint64_t    DE_READABLE                 : 1,
                        //! Entry is writable by the user who queried this entry.
                        DE_WRITABLE                 : 1,
                        //! Entry is valid for all subentries of this namespace.
                        DE_NAMESPACE_ENTRY          : 1,
                                                    : 0;
        };
    };

    //! Double-linked list pointers.
    struct disir_entry *next, *prev;
};


//! \brief Free a entry structure returned from a I/O API.
//!
//! \return DISIR_STATUS_OK
enum disir_status
disir_entry_finished (struct disir_entry **entry);

//! \brief Input a config entry from the disir instance.
//!
//! Read a Config object from `disir` identified by ID `entry_id`.
//! The `mold` argument may optionally override the internal mold associated
//! wth `entry_id`. If supplied, it is the callers responsibility to invoke disir_mold_finished()
//! on this instance. Normally, this argument should be NULL.
//!
//! \param[in] instance Library instance.
//! \param[in] group_id String identifier for the which group to look for entry.
//! \param[in] entry_id String identifier for the config entry to read.
//! \param[in] mold Optional mold that describes the config to parse. If NULL,
//!     I/O plugin must locate a mold instead.
//! \param[out] config Object to populate with the state read from 'id'
//!
//! \return DISIR_STATUS_INVALID_ARGUMENT if either of arguments `disir`,
//      `entry_id` or `config` are NULL.
//! \return DISIR_STATUS_NO_CAN_DO if the matching plugin
//!     for some reason does not implement config_write operation.
//! \return DISIR_STATUS_NOT_EXIST if the plugin associated with `config`
//!     is not registered with `disir`.
//! \return DISIR_STATUS_INVALID_CONTEXT is returned when the config retrieved is invalid
//!     according to its mold definition. disir_error is not set on the instance, since the
//!     invalid state lies in the individual context elements of the config. Iterate all child
//!     contexts and test state retrieve the erroneous state.
//! \return status of the plugin config_read operation.
//!
enum disir_status
disir_config_read (struct disir_instance *instance, const char *group_id, const char *entry_id,
                   struct disir_mold *mold, struct disir_config **config);

//! \brief Output the config object to the disir instance.
//!
//! \param[in] instance Library instance.
//! \param[in] group_id String identifier for the which group to look for entry.
//! \param[in] entry_id String identifier for output location.
//! \param[in] config The config object to output.
//!
//! \return DISIR_STATUS_INVALID_ARGUMENT if either of the input arguments are NULL.
//! \return DISIR_STATUS_NO_CAN_DO if the `config` object is not associated with a plugin.
//! \return DISIR_STATUS_NO_CAN_DO if the matching plugin
{'fraction_non_alphanumeric': 0.08901426108760382, 'fraction_numerical': 0.0025074439742986993, 'mean_word_length': 2.50082281952825, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3903478', 'n_tokens_mistral': 1819, 'n_tokens_neox': 1702, 'n_words': 707}