-
Notifications
You must be signed in to change notification settings - Fork 0
Documentation
This library is designed to make it easy to create tools that run on the terminal. Below it will be analyzed how it can be used.
#define TOOL_BUILDER_WRONG_ARG_NUM -1 // Wrong argument number.
#define TOOL_BUILDER_WRONG_NAME_OR_ALIAS -2 // Wrong name or alias.
#define TOOL_BUILDER_EMPTY_NAME -3 // No command has been requested.
#define TOOL_BUILDER_NO_ACTION_DEFINED -4 // No function has been defined for the specific command.
#define TOOL_BUILDER_FAILED_TO_ADD -5 // Failed to add an element to the builder.
#define TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS -7 // The command that was requested does not exists.#define TOOL_BUILDER_V 1.6The builder structure is the most basic element of the library. It contains all the necessary information for the construction of the requested tool.
struct tool_builder
{
struct tool_builder_command *t_commands; // array of commands.
int t_commandsc; // The number of the commands.
struct tool_builder_help t_help; // The help of the tool.
int t_mc: 1; // enable or disable multiple commands in one line.
};The user should not be interested in the above definition.
The parameter structure is the structure that is "sent" to the user function that executes a command. It is used so that the user (tool developer) receives the necessary information about the command that was executed.
struct tool_builder_args
{
char *c_name; // The name of the command that has been executed.
char *c_used_alias; // The alias that has been used.
char *(*c_values); // The values that has been retrieved.
int c_argc; // The arguments of the command.
struct tool_builder *c_builder; // The builder.
};Above is the information he receives.
The tool_builder_init function initializes the tool builder.
void tool_builder_init(struct tool_builder *c_builder);c_builder Is a pointer to the builder to be used.
--
--
struct tool_builder builder;
tool_builder_init(&builder);The tool_builder_destroy function frees the memory that the builder has reserved. It should be called when the builder is no longer useful.
void tool_builder_destroy(struct tool_builder *c_builder);c_builder Is pointer to the builder used and no longer needed.
--
--
struct tool_builder builder;
tool_builder_init(&builder);
... code ...
tool_builder_destroy(&builder);The tool_builder_add_command function adds a new command to the tool. This means that if a user using the tool you created calls the command name specified in this function, a certain action that is also defined in this function will be performed.
int tool_builder_add_command(struct tool_builder *c_builder, const char *c_name,
int c_argc, void (*c_callback)(const struct tool_builder_args *info));c_builder Is a pointer to the builder to be used.
c_name The name of the command.
c_argc The number of parameters required by the command.
c_callback The action to be taken if the user requests this command. The function that plays the role of the command action must have the below signature
void your_action(const struct tool_builder_args *info);All information about the command inputs is given as a parameter in this action. Check tool_builder_args struct for more details.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the new command.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// code.
tool_builder_destroy(&builder);
}The tool_builder_add_alias function looks like the tool_builder_add_command function. The difference is that instead of adding a new command, it adds to a specific command 1, 2, .... , n names that describe the same command. Such names could be abbreviations, in order to make it easier for the user to remember.
int tool_builder_add_alias(struct tool_builder *c_builder, const char *c_name, const char *c_alias, ...);c_builder Is a pointer to the builder to be used.
c_name The name of the command to add the aliases.
c_alias The multitude of aliases. The last alias must be NULL.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS The command to which it went to add the aliases does not exist.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the aliases.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// add the aliases.
tool_builder_add_alias(&builder, "Testing", "Test", "t", "T", NULL);
// code.
tool_builder_destroy(&builder);
}The tool_builder_set_action function changes or sets an action on a command.
int tool_builder_set_action(struct tool_builder *c_builder, const char *c_name,
void (*c_callback)(const struct tool_builder_args *info));c_builder Is a pointer to the builder to be used.
c_name The name of the command that should perform this action.
c_callback The action to be performed on the command.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS The command c_name does not exists in the builder.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
// adding a command without setting an action.
tool_builder_add_command(&builder, "Testing", 2, NULL);
// set the action.
tool_builder_set_action(&builder, "Testing", &testing_command_action);
// code.
tool_builder_destroy(&builder);
}The tool_builder_prepare function makes all the necessary preparations in the builder to execute the command(s) requested by the terminal.
int tool_builder_prepare(int argc, char *argv[], const struct tool_builder *c_builder);argc The number of parameters given in the executable. Given by the main function.
argv Pointer that pointes to the first parameter. Given by the main function.
c_builder Is a pointer to the builder to be used.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_EMPTY_NAME No executable parameters were given
TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS The parameter given to the executable does not correspond to a command.
TOOL_BUILDER_NO_ACTION_DEFINED The requested command does not have a specified action.
TOOL_BUILDER_WRONG_ARG_NUM The parameters provided are not sufficient for the requested command.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// prepare for execution.
tool_builder_prepare(argc, argv, &builder);
// code.
tool_builder_destroy(&builder);
}The tool_builder_execute function is responsible for executing any command requested by the terminal in the executable. If more than one command is given, it will be executed in the order given, from left to right.
void tool_builder_execute();--
--
--
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// prepare for execution.
tool_builder_prepare(argc, argv, &builder);
// exete the commands.
tool_builder_execute();
// code.
tool_builder_destroy(&builder);
}The tool_builder_call_command function allows the tool developer to execute a tool command without the user requesting it from the terminal. The command requested by the programmer should have no parameters.
int tool_builder_call_command(const char *c_name, const struct tool_builder *c_builder);c_name The name of the command to be executed.
c_builder Is a pointer to the builder to be used.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_WRONG_NAME_OR_ALIAS There is no command with this name.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
tool_builder_init_help(&c_builder, "your-tool-name");
// prepare for execution.
if (tool_builder_prepare(argc, argv, &builder) == TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS)
{
// call the --help command.
tool_builder_call_command("--help", &builder);
}
// code.
tool_builder_destroy(&builder);
}The tool_builder_init_help function generates a --help command along with the -h aliases and adds it to the tool with a default action. This action can be changed if you do not please the developer.
int tool_builder_init_help(struct tool_builder *c_builder, const char *tool_name);c_builder Is a pointer to the builder to be used.
tool_name The name of the tool.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the new command or alias.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// initialize the pre build help command.
tool_builder_init_help(&builder, "your-tool-name");
tool_builder_destroy(&builder);
}The tool_builder_set_desc function sets a description of the tool, which will appear when someone calls the --help command.
int tool_builder_set_desc(struct tool_builder *c_builder, const char *c_description);c_builder Is a pointer to the builder to be used.
c_description A general description of the tool.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add description.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// initialize the pre build help command.
tool_builder_init_help(&builder, "your-tool-name");
// set description.
tool_builder_set_desc(&builder, "A general description of your tool.");
tool_builder_destroy(&builder);
}The tool_builder_add_command_doc function adds the name of a command, along with its accompanying description to the tool instructions. These instructions can be displayed using the --help command.
int tool_builder_add_command_doc(struct tool_builder *c_builder, const char *c_name,
const char *c_description);c_builder Is a pointer to the builder to be used.
c_name The name of the command to add.
c_description The description of the command.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the command or description.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// initialize the pre build help command.
tool_builder_init_help(&builder, "your-tool-name");
// set description.
tool_builder_set_desc(&c_builder, "A general description of your tool.");
// add testing command to docs.
tool_builder_add_command_doc(&builder, "Testing", "Command description");
tool_builder_destroy(&builder);
}The tool_builder_add_command_doc function adds the aliases of a command to the tool instructions. These instructions can be displayed using the --help command. The aliases do not need to be given again because they already exist in the builder. They are in the command structure.
int tool_builder_add_alias_doc(struct tool_builder *c_builder, const char *c_name);c_builder Is a pointer to the builder to be used.
c_name The name of the command that has these aliases.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS The command does not exists.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// initialize the pre build help command.
tool_builder_init_help(&builder, "your-tool-name");
// set description.
tool_builder_set_desc(&c_builder, "A general description of your tool.");
// add testing command to docs.
tool_builder_add_command_doc(&builder, "Testing", "Command description");
// add aliases to docs.
tool_builder_add_alias_doc(&builder, "Testing");
tool_builder_destroy(&builder);
}The tool_builder_set_closing_desc function sets another description, which appears at the end of the document that appears when the --help command is executed.
int tool_builder_set_closing_desc(struct tool_builder *c_builder, const char *close_description);c_builder Is a pointer to the builder to be used.
close_description Something like an epilogue to the reference to a source.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add closing description.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_add_command(&builder, "Testing", 2, &testing_command_action);
// initialize the pre build help command.
tool_builder_init_help(&c_builder, "your-tool-name");
// set description.
tool_builder_set_desc(&builder, "A general description of your tool.");
// set closing description.
tool_builder_set_closing_desc(&builder, "For more informations look at https://example.com");
tool_builder_destroy(&builder);
}The tool_builder_add_both function is a shortcut that executes the tool_builder_add_command and tool_builder_add_command_doc functions but by calling only one function.
int inline tool_builder_add_both(struct tool_builder *c_builder, const char *c_name,
int c_argc, void (*c_callback)(const struct tool_builder_args *info),
const char *c_description)c_builder Is a pointer to the builder to be used.
c_name The name of the command.
c_argc The number of parameters required by the command.
c_callback The action to be taken if the user requests this command. The function that plays the role of the command action must have the below signature
void your_action(const struct tool_builder_args *info);All information about the command inputs is given as a parameter in this action. Check tool_builder_args struct for more details.
c_description The description of the command.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the new command or the description.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
// initialize the pre build help command.
tool_builder_init_help(&c_builder, "your-tool-name");
// add a command with the description on the docs in one command.
tool_builder_add_both(&builder, "Testing", 2, &testing_command_action, "Command description");
tool_builder_destroy(&builder);
}The tool_builder_add_alias_both function is a shortcut that executes the tool_builder_add_alias and tool_builder_add_alias_doc functions but by calling only one function.
int inline tool_builder_add_alias_both(struct tool_builder *c_builder, const char *c_name,
const char *c_alias, ...)c_builder Is a pointer to the builder to be used.
c_name The name of the command to add the aliases.
c_alias The multitude of aliases. The last alias must be NULL.
It returns zero when everything went well. In the event of an error, one of the following may be returned.
TOOL_BUILDER_NO_SUCH_COMMAND_EXISTS The command to which it went to add the aliases does not exist.
TOOL_BUILDER_FAILED_TO_ADD Failed to add the aliases.
void testing_command_action(const struct tool_builder_args *info)
{
// code.
}
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
// initialize the pre build help command.
tool_builder_init_help(&c_builder, "your-tool-name");
// add a command with the description on the docs in one command.
tool_builder_add_both(&builder, "Testing", 2, &testing_command_action, "Command description");
// add aliases in command and on the docs.
tool_builder_add_alias_both(&builder, "Testing", "Test", "T", "t", NULL);
tool_builder_destroy(&builder);
}The tool_builder_set_mc function allows the developer to disable the library function that allows more than one command to execute on the same terminal line.
void inline tool_builder_set_mc(struct tool_builder *c_builder, int state);c_builder Is a pointer to the builder to be used.
state The new state. '1' to enable or '0' to disable. By default is '1'.
--
--
int main(int argc, char *argv[])
{
struct tool_builder builder;
tool_builder_init(&builder);
tool_builder_set_mc(&builder, 0); // disable feature.
tool_builder_destroy(&builder);
}An example of the library in use can be found in the tests folder
This is my library, I hope you find it useful. Any contribution or any proposal for change is acceptable!!