klish/lub/argv.h

/*
 * argv.h
 */
/**
\ingroup lub
\defgroup lub_argv argv
@{

\brief This utility provides a simple means of manipulating a vector of 
command textual words.

A word is either separated by whitespace, or if quotes are used a word is
defined by the scope of the quotes.

e.g.
\verbatim
one two "this is the third word" four
\endverbatim
contains four "words" the third of which is a string.

*/
#ifndef _lub_argv_h
#define _lub_argv_h

#include <stddef.h>

#include "c_decl.h"
#include "types.h"

_BEGIN_C_DECL

/**
 * This type is used to reference an instance of an argument vector
 */
typedef struct lub_argv_s lub_argv_t;

/*=====================================
 * ARGV INTERFACE
 *===================================== */
/**
 * \pre
 * - none
 *
 * \return
 * The number of space separated words in the specified string.
 *
 * \post
 * - none
 */
unsigned
    lub_argv_wordcount(
        /** 
         * The string to analyse
         */
        const char *line
    );
/**
 *  This operation is used to construct an instance of this class. The client
 * species a string and an offset within that string, from which to start 
 * collecting "words" to place into the vector instance.
 *
 * \pre
 * - none
 *
 * \return
 * - A instance of an argument vector, which represents the words contained in
 * the provided string. 
 * - NULL if there is insuffcient resource
 *
 * \post
 * - The client becomes resposible for releasing the instance when they are
 *   finished with it, by calling lub_argv_delete()
 */
lub_argv_t *
    lub_argv_new(
        /** 
         * The string to analyse
         */            
        const char *line,
        /** 
         * The offset in the string to start from
         */
        size_t offset
    );
            
void
    lub_argv_delete(lub_argv_t *instance);
unsigned
    lub_argv__get_count(const lub_argv_t *instance);
const char *
    lub_argv__get_arg(const lub_argv_t *instance,
                      unsigned          index);
size_t
    lub_argv__get_offset(const lub_argv_t *instance,
                         unsigned          index);
bool_t
    lub_argv__get_quoted(const lub_argv_t *instance,
                         unsigned          index);
void
    lub_argv__set_arg(lub_argv_t *instance,
                      unsigned    index,
                      const char *arg);
char **
    lub_argv__get_argv(const lub_argv_t *instance, char *argv0);
const char *
    lub_argv__get_line(const lub_argv_t *instance);

_END_C_DECL

#endif /* _lub_argv_h */
/** @} lub_argv */