cli.h

Go to the documentation of this file.

/* Copyright 2012-2014, Peter A. Bigot
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * * Neither the name of the software nor the names of its contributors may be
 *   used to endorse or promote products derived from this software without
 *   specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef BSP430_UTILITY_CLI_H
#define BSP430_UTILITY_CLI_H

#include <bsp430/core.h>

#ifndef configBSP430_CLI_COMMAND_COMPLETION
#define configBSP430_CLI_COMMAND_COMPLETION 0
#endif /* configBSP430_CLI_COMMAND_COMPLETION */

#ifndef configBSP430_CLI_COMMAND_COMPLETION_HELPER
#define configBSP430_CLI_COMMAND_COMPLETION_HELPER 0
#endif /* configBSP430_CLI_COMMAND_COMPLETION_HELPER */

const char * xBSP430cliNextToken (const char ** commandp,
                                  size_t * remainingp,
                                  size_t * lenp);

const char * xBSP430cliNextQToken (const char ** commandp,
                                   size_t * remainingp,
                                   size_t * lenp);

/* Forward declarations */
struct sBSP430cliCommand;
struct sBSP430cliCommandLink;
struct sBSP430cliCompletionData;
struct sBSP430cliCompletionHelper;

typedef struct sBSP430cliCommandLink {
  struct sBSP430cliCommandLink * link;

  const struct sBSP430cliCommand * command_set;

  const struct sBSP430cliCommand * cmd;

} sBSP430cliCommandLink;

typedef void (* vBSP430cliCompletionHelper) (const struct sBSP430cliCompletionHelper * self,
                                             const char * argstr,
                                             size_t argstr_len,
                                             struct sBSP430cliCompletionData * cdp);

typedef struct sBSP430cliCompletionHelper {
  vBSP430cliCompletionHelper helper;
} sBSP430cliCompletionHelper;

typedef struct sBSP430cliCompletionHelperStrings {
  sBSP430cliCompletionHelper completion_helper;

  const char * const * strings;

  size_t len;
} sBSP430cliCompletionHelperStrings;

void vBSP430cliCompletionHelperStrings (const struct sBSP430cliCompletionHelper * self,
                                        const char * argstr,
                                        size_t argstr_len,
                                        struct sBSP430cliCompletionData * cdp);

const char * const * xBSP430cliHelperStringsExtract (const struct sBSP430cliCompletionHelperStrings * chsp,
                                                     const char ** argstrp,
                                                     size_t * argstr_lenp);

typedef int (* iBSP430cliHandlerFunction) (struct sBSP430cliCommandLink * chain,
                                           void * param,
                                           const char * argstr,
                                           size_t argstr_len);

typedef int (* iBSP430cliSimpleHandler) (const char * argstr);

typedef struct sBSP430cliCommand {
  const char * key;

  const char * help;

#if defined(BSP430_DOXYGEN)                                     \
  || ((configBSP430_CLI_COMMAND_COMPLETION - 0)                 \
      && (configBSP430_CLI_COMMAND_COMPLETION_HELPER - 0))

  const sBSP430cliCompletionHelper * completion_helper;
#endif /* configBSP430_CLI_COMMAND_COMPLETION_HELPER */

  const struct sBSP430cliCommand * const child;

  const struct sBSP430cliCommand * const next;

  iBSP430cliHandlerFunction const handler;

  union uParam {
    void * const ptr;

    iBSP430cliSimpleHandler const simple_handler;
  } param;

} sBSP430cliCommand;

typedef struct sBSP430cliMatchCallback {
  void (* callback) (struct sBSP430cliMatchCallback * self,
                     const sBSP430cliCommand * cmd);
} sBSP430cliMatchCallback;

int iBSP430cliMatchCommand (const sBSP430cliCommand * cmds,
                            const char * command,
                            size_t command_len,
                            const sBSP430cliCommand ** matchp,
                            sBSP430cliMatchCallback * match_callback,
                            const char ** argstrp,
                            size_t * argstr_lenp);

int iBSP430cliExecuteCommand (const sBSP430cliCommand * cmds,
                              void * param,
                              const char * command);

int
iBSP430cliParseCommand (const sBSP430cliCommand * cmds,
                        void * param,
                        const char * command,
                        iBSP430cliHandlerFunction chain_handler,
                        iBSP430cliHandlerFunction handler);

int iBSP430cliStoreExtractedI (const char ** argstrp,
                               size_t * argstr_lenp,
                               int * destp);

int iBSP430cliStoreExtractedUI (const char ** argstrp,
                                size_t * argstr_lenp,
                                unsigned int * destp);

int iBSP430cliStoreExtractedL (const char ** argstrp,
                               size_t * argstr_lenp,
                               long * destp);

int iBSP430cliStoreExtractedUL (const char ** argstrp,
                                size_t * argstr_lenp,
                                unsigned long * destp);

int iBSP430cliHandlerSimple (sBSP430cliCommandLink * chain,
                             void * param,
                             const char * argstr,
                             size_t argstr_len);

int iBSP430cliHandlerStoreI (struct sBSP430cliCommandLink * chain,
                             void * param,
                             const char * argstr,
                             size_t argstr_len);

int iBSP430cliHandlerStoreUI (struct sBSP430cliCommandLink * chain,
                              void * param,
                              const char * argstr,
                              size_t argstr_len);

int iBSP430cliHandlerStoreL (struct sBSP430cliCommandLink * chain,
                             void * param,
                             const char * argstr,
                             size_t argstr_len);

int iBSP430cliHandlerStoreUL (struct sBSP430cliCommandLink * chain,
                              void * param,
                              const char * argstr,
                              size_t argstr_len);

enum eBSP430cliErrorType {
  eBSP430_CLI_ERR_NONE,

  eBSP430_CLI_ERR_Config,

  eBSP430_CLI_ERR_Missing,

  eBSP430_CLI_ERR_Unrecognized,

  eBSP430_CLI_ERR_MultiMatch,

  eBSP430_CLI_ERR_Invalid,

  eBSP430_CLIERRORTYPES,
};

typedef int (* iBSP430cliDiagnosticFunction) (sBSP430cliCommandLink * chain,
                                              enum eBSP430cliErrorType errtype,
                                              const char * argstr,
                                              size_t argstr_len);

void vBSP430cliSetDiagnosticFunction (iBSP430cliDiagnosticFunction diagnostic_function);

int iBSP430cliNullDiagnostic (sBSP430cliCommandLink * chain,
                              enum eBSP430cliErrorType errtype,
                              const char * argstr,
                              size_t argstr_len);

#if defined(BSP430_DOXYGEN) || (BSP430_CONSOLE - 0)
int iBSP430cliConsoleDiagnostic (sBSP430cliCommandLink * chain,
                                 enum eBSP430cliErrorType errtype,
                                 const char * argstr,
                                 size_t argstr_len);
#endif /* configBSP430_CONSOLE */

#if defined(BSP430_DOXYGEN) || (BSP430_CONSOLE - 0)
void vBSP430cliConsoleDisplayChain (struct sBSP430cliCommandLink * chain,
                                    const char * argstr);
#endif /* configBSP430_CONSOLE */


#if defined(BSP430_DOXYGEN) || (BSP430_CONSOLE - 0)
void vBSP430cliConsoleDisplayHelp (const sBSP430cliCommand * cmd);
#endif /* configBSP430_CONSOLE */

sBSP430cliCommandLink * xBSP430cliReverseChain (sBSP430cliCommandLink * chain);

#if defined(BSP430_DOXYGEN) || ! defined(BSP430_CLI_CONSOLE_BUFFER_SIZE)
#define BSP430_CLI_CONSOLE_BUFFER_SIZE 0
#endif /* BSP430_CLI_CONSOLE_BUFFER_SIZE */

typedef enum eBSP430cliConsole {
  eBSP430cliConsole_READY = 0x01,

  eBSP430cliConsole_REPAINT = 0x02,

  eBSP430cliConsole_DO_COMPLETION = 0x04,

  eBSP430cliConsole_PROCESS_ESCAPE = 0x08,

  eBSP430cliConsole_IN_ESCAPE = 0x10,

  eBSP430cliConsole_ANY_ESCAPE = eBSP430cliConsole_PROCESS_ESCAPE | eBSP430cliConsole_IN_ESCAPE,

  eBSP430cliConsole_REPAINT_BEL = 0x100,

  eBSP430cliConsole_COMPLETE_SPACE = 0x200,

} eBSP430cliConsole;

typedef struct sBSP430cliCompletionData {
  const char * command;

  size_t command_len;

  const sBSP430cliCommand * command_set;

  const char ** returned_candidates;

  size_t max_returned_candidates;

  size_t ncandidates;

  const char * append;

  size_t append_len;
} sBSP430cliCompletionData;

void vBSP430cliCompletionHelperCallback (sBSP430cliCompletionData * cdp,
                                         const char * candidate);

const char * xBSP430cliConsoleBuffer (void);

#if defined(BSP430_DOXYGEN) || (0 < BSP430_CLI_CONSOLE_BUFFER_SIZE)
void vBSP430cliConsoleBufferClear (void);
#endif /* BSP430_CLI_CONSOLE_BUFFER_SIZE */

#if defined(BSP430_DOXYGEN) || (0 < BSP430_CLI_CONSOLE_BUFFER_SIZE)
int iBSP430cliConsoleBufferExtend (const char * text, size_t len);
#endif /* BSP430_CLI_CONSOLE_BUFFER_SIZE */

#if defined(BSP430_DOXYGEN) || (0 < BSP430_CLI_CONSOLE_BUFFER_SIZE)
int iBSP430cliConsoleBufferProcessInput (void);
#endif /* BSP430_CLI_CONSOLE_BUFFER_SIZE */

int iBSP430cliConsoleBufferConsumeEscape (int flags);

#if defined(BSP430_DOXYGEN) || (configBSP430_CLI_COMMAND_COMPLETION - 0)
int iBSP430cliCommandCompletion (sBSP430cliCompletionData * cdp);
#endif /* configBSP430_CLI_COMMAND_COMPLETION */

#ifndef BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS

#define BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS 5
#endif /* BSP430_CLI_CONSOLE_BUFFER_MAX_COMPLETIONS */

#if defined(BSP430_DOXYGEN) || (configBSP430_CLI_COMMAND_COMPLETION - 0)
int iBSP430cliConsoleBufferCompletion (const sBSP430cliCommand * command_set,
                                       const char ** commandp);
#endif /* configBSP430_CLI_COMMAND_COMPLETION */

#endif /* BSP430_UTILITY_CLI_H */