libcmdf.h

A simple library for writing command-line applications, inspired by Python's cmd module.

Latest version: v.1.3.1 (2022-11-18)

Features

Written using 100% ANSI C
Header only: no linkage! No separate compilation!
Cross-platform
GNU Readline support
Can be used from C++ (without -fpermissive)

Requirements

Any ANSI C/ISO C90-compliant compiler
Tested on GCC 5.4+, clang 4.0+ and MSVC 14.0
Linux/Windows
Tested on Ubuntu 16.04 - 20.04, Fedora 26 - 30, and Windows 10 (all AMD64)
GNU Readline development libraries (optional)
Required for GNU Readline support, if enabled.

Usage

Being a header-only library, you don't need to do any complex linkage - just drop it in your project tree and you're done!

You will, however, need to define LIBCMDF_IMPL only once, and before you include the library, like this:

#define LIBCMDF_IMPL
#include <libcmdf.h>

...

API in a nutshell

First of all, you must initialize libcmdf by calling either cmdf_init_quick() or cmdf_init:

void cmdf_init(const char *prompt, const char *intro, const char *doc_header,
               const char *undoc_header, char ruler, int use_default_exit);
#define cmdf_init_quick() cmdf_init(NULL, NULL, NULL, NULL, 0, 1)

The two most important parameters are the prompt and the intro:

prompt - The prompt for every command.
intro - A text that is displayed to the user on program startup.

After initialization is done, you must then register some command callbacks. A command callback has a command name associated with it, and that can be executed by the user, which in turn will execute the associated command callback.

The command callback has the following format:

typedef CMDF_RETURN (* cmdf_command_callback)(cmdf_arglist *arglist);

CMDF_RETURN is a typedefd integer specifying a return code. arglist is a pointer to the arguments passed by the user along with the command, which libcmdf transperantly handles behind the scenes. It is destroyed by libcmdf when the command callback returns.

This simple structure contains two elements:

/* libcmdf command list and arglist */
typedef struct cmdf___arglist_s {
     char **args;                /* NULL-terminated string list */
     size_t count;               /* Argument list count */
} cmdf_arglist;

This way you can quickly iterate the command-line arguments and act accordingly.

After you have your command callback, simply register it using cmdf_register_command:

CMDF_RETURN cmdf_register_command(cmdf_command_callback callback, const char *cmdname,
                                  const char *help);

Note that you may provide an optional help message. If you do, the user will be able to see it when and if he will request it using the help command.

After that, initialization of the library is pretty much complete, so you can just call the main command loop:

cmdf_commandloop();

In any case you may refer to test.c for a working example.

Configuration

The library can be configured by #defineing any of the following definitions only once, before including the library:

Definition	Description	Default
`CMDF_MAX_COMMANDS`	Maxmium amount of allowed commands.	24
`CMDF_TAB_TO_SPACES`	If a tab is encountered in a command's help string, expand it to N spaces.	8
`CMDF_READLINE_SUPPORT`	Enable/disable GNU readline support (Linux only, requires readline development libraries)	(Disabled)
`CMDF_FGETS`	A `fgets()`-like function, to be used for command-line input.	`fgets()`
`CMDF_MALLOC`	A `malloc()`-like function, to be used for memory allocations¹.	`malloc()`
`CMDF_FREE`	A `free()`-like function, to be used for memory deallocations¹.	`free()`
`CMDF_MAX_INPUT_BUFFER_LENGTH`	The maximum length of the input buffer used to get user input¹.	256
`CMDF_STDOUT`	A `FILE *` to be used as standard output.	`stdout`
`CMDF_STDIN`	A `FILE *` to be used as standard input.	`stdin`

¹ Note: GNU Readline will not use any custom memory allocation functions, but rather the standard library's malloc and free. Also, you may have to provide additional linker flags to link against readline.

To configure libcmdf simply define any configuration definitions once and before LIBCMDF_IMPL, like so:

#define CMDF_READLINE_SUPPORT   /* Enable readline support */
#define LIBCMDF_IMPL
#include <libcmdf.h>

...

Feedback

I tested the library to the best of my abilities, but there might still be some bugs.
If you do find them, please contact me or open an issue!

FAQ

Is the library thread-safe?

No, but it's just handling user input for CLI, so I honestly don't think it should be.

Why is `cmdf_quit` not implemented?

At the moment, the initialization routines don't allocate any memory, or perform any weird initialization tricks that require deinitalization.

This might change in the future, though, so make sure to call cmdf_quit when you're done with it!

Any plans to support Linenoise/anything else?

Yes! I'm planning to add support for it in the near future.

Any plans to implement a proper C++ API?

Yes! Near future, hopefully!

License

This software is dual-licensed to the public domain and under the following license: you are granted a perpetual, irrevocable license to copy, modify, publish and distribute this file as you see fit.

ruier/libcmdf