varch/doc/command.en.md

Introduction

The command prompt is a working prompt in the operating system that prompts for command input. It is a convenient human-computer interaction interface. This command parsing module does not involve receiving commands entered from the console for the time being, but rather processes string commands.

Interface

Command Export

int command_export(const char *name, command_handle_t handle);

Before introducing the command parsing function, let's first look at the command export function. This function is used to add supported functions, matching the name with the corresponding callback function. The name is the function identification name (generally, the function name is used as the identification name for command parsing), and the handle is the corresponding callback processing function. It returns 1 if the export is successful and 0 if it fails.

typedef int (*command_handle_t)(int argc, char *argv[]);

The definition of the command_handle_t function type is consistent with our commonly used int main(int argc, char *argv[]). Parameters are passed in through argc and argv.

Command Execution

int command(const char *line);

The command execution function is also very simple. Just pass in the command line. It returns the return value of the function corresponding to the recognized command. -1 is the return value when the parsing fails. Therefore, when defining the processing function, the return value cannot be -1. The input format of the command:

argv[0] argv[1] argv[2]...

Among them, argv[0] is the command identifier, and several parameters can follow it. The number is passed to the function through argc. Command parameters are separated by spaces. When you want to input spaces within a parameter, you need to use the escape character backslash \ for escaping. "\ " represents a space. Besides, the escape characters that are also supported include: double quotation marks " and backslash \. To simplify the use of escape characters, you can use a pair of double quotation marks to enclose commands that do not need escape parsing. Usage Example:

int func1(int argc, char *argv[])
{
	printf("I am func1!\r\n");
	printf("argc = %d\r\n", argc);
	for (int i = 0; i < argc; i++)
	{
		printf("argv[%d] = %s\r\n", i, argv[i]);
	}
	return 1;
}

int func2(int argc, char *argv[])
{
	printf("I am func2!\r\n");
	return 1;
}

int func3(int argc, char *argv[])
{
	printf("I am func3!\r\n");
	return 1;
}

static void test(void)
{
    /* Export commands */
	command_export("func1", func1);
	command_export("func2", func2);
	command_export("func3", func3);

	command("cmd -l"); // The built-in command of the module, used to view the currently supported commands
	printf("--------------------------\r\n");
	command("func2");
	printf("--------------------------\r\n");
	command("func3");
	printf("--------------------------\r\n");
	command("func1 1 2 3"); // Without escaping, each space-separated part will become a separate parameter
	printf("--------------------------\r\n");
	command("func1 1\\ 2 3"); // The space after 1 is escaped, and 1 and 2 will be combined with the space in between
	printf("--------------------------\r\n");
	command("func1 \"1 2 3\""); // "1 2 3" between double quotation marks will be parsed as one parameter
}

Result:

cmd
func1
func2
func3
count = 4
--------------------------
I am func2!
--------------------------
I am func3!
--------------------------
I am func1!
argc = 4
argv[0] = func1
argv[1] = 1
argv[2] = 2
argv[3] = 3
--------------------------
I am func1!
argc = 3
argv[0] = func1
argv[1] = 1 2
argv[2] = 3
--------------------------
I am func1!
argc = 2
argv[0] = func1
argv[1] = 1 2 3

Among them, cmd is a built-in command that counts the currently supported commands and returns the number of supported commands.

Command Clear

void command_clear(void);

Clear all exported commands.