Command Pattern

Diagram of the command pattern

The Command pattern is used to associate an object with an operation that is deferred to at later time for execution. The command itself is an object that contains the target of the command (known as the receiver) along with the operation to perform on the target. This means the command object can be treated like any other object, even putting it into a list.

A common application for the Command pattern is an undo buffer. Another application is a batch processor.

At its heart, a Command object takes two parameters: The object to work on and an operation to use. The operation is typically a function pointer (in C++) or a delegate (in C#). A Command object can hold additional parameters if the associated operation requires additional parameters.

When invoked, the Command object calls the operation with the receiver object and whatever additional parameters that might be required. The invocation is typically a single method called execute() so all Command objects look the same to the entity doing the invocation of the Commands.

It is typical for the Command objects to be created by one entity and passed to another entity for invocation.

How to Use

Links to the Command classes

C++	C#	Python	C
Command_TextObject class	Command_TextObject class	Command_TextObject class	Command_TextObject class
Command class	Command class	Command class	Command class

For example, a program that supports undo would work like this (this is a simplistic undo):

1. Define all operations as functions that takes a single receiver (of the command) to operate on, along with any necessary additional parameters.
2. Any time an operation other than Undo is invoked by the user:
   1. Create a Command object with the function for that operation along with the receiver on which the function applies
   2. Store the Command object in the undo container
   3. Invoke the Command object just created
3. Repeat step 2 until the user selects Undo.
4. Perform the Undo:
   1. If there are any commands to undo then
   2. Completely reset the receiver that all commands are applied to
   3. Remove the last Command object from the undo container, if any
   4. For all Command objects in the undo container, invoke each Command in order (oldest to newest) on the receiver. This puts the receiver back into the state it was in before the last command was applied.

This example implements the above algorithm. A Command_TextObject instance represents the target of the commands. The commands themselves are stored in a Command instance. A simple stack is used to remember the commands in the order in which they are applied. After several commands are applied, the commands are undone in reverse order.

Note: In C++, a std::vector<> is used instead of a std::stack<> because there is no way to iterate over the contents of a stack.

C++

    void Command_Exercise()
    {
        std::cout << std::endl;
        std::cout << "Command Exercise" << std::endl;
 
        // The base text object to work from.
        Command_TextObject::shared_ptr_t text = std::make_shared<Command_TextObject>("This is a line of text on which to experiment.");
 
        std::cout << Helpers::formatstring("  Starting text: \"%s\"", text->ToString().c_str()) << std::endl;
 
        // Apply four operations to the text.
        Command_ApplyReplaceCommand(text, "text", "painting");
        Command_ApplyReplaceCommand(text, "on", "off");
        Command_ApplyReverseCommand(text);
        Command_ApplyReplaceCommand(text, "i", "!");
 
        std::cout << "  Now perform undo until back to original" << std::endl;
 
        // Now undo the four operations.
        Command_Undo(text);
        Command_Undo(text);
        Command_Undo(text);
        Command_Undo(text);
 
        std::cout << Helpers::formatstring("  Final text   : \"%s\"", text->ToString().c_str()) << std::endl;
 
        std::cout << "  Done." << std::endl;
    }

C#

        public void Run()
        {
            Console.WriteLine();
            Console.WriteLine("Command Exercise");
 
            // Start with a fresh undo list.
            _commandUndoList.Clear();
 
            // The base text object to work from.
            Command_TextObject text = new Command_TextObject("This is a line of text on which to experiment.");
 
            Console.WriteLine("  Starting text: \"{0}\"", text);
 
            // Apply four operations to the text.
            Command_ApplyReplaceCommand(text, "text", "painting");
            Command_ApplyReplaceCommand(text, "on", "off");
            Command_ApplyReverseCommand(text);
            Command_ApplyReplaceCommand(text, "i", "!");
 
            Console.WriteLine("  Now perform undo until back to original");
 
            // Now undo the four operations.
            Command_Undo(text);
            Command_Undo(text);
            Command_Undo(text);
            Command_Undo(text);
 
            Console.WriteLine("  Final text   : \"{0}\"", text);
 
            Console.WriteLine("  Done.");
        }

Python

def Command_Exercise():
    print()
    print("Command Exercise")
 
    # The base text object to work from.
    text = Command_TextObject("This is a line of text on which to experiment.")
 
    print("  Starting text: \"{0}\"".format(text.ToString()))
 
    # Apply four operations to the text.
    Command_ApplyReplaceCommand(text, "text", "painting")
    Command_ApplyReplaceCommand(text, "on", "off")
    Command_ApplyReverseCommand(text)
    Command_ApplyReplaceCommand(text, "i", "!")
 
    print("  Now perform undo until back to original")
 
    # Now undo the four operations.
    Command_Undo(text)
    Command_Undo(text)
    Command_Undo(text)
    Command_Undo(text)
 
    print("  Final text   : \"{0}\"".format(text.ToString()))
 
    print("  Done.")

C

void Command_Exercise(void)
{
    printf("\nCommand_Exercise\n");
 
    Command_TextObject textObject = { 0 };
    if (Command_TextObject_Initialize(&textObject, "This is a line of text on which to experiment."))
    {
        printf("  Starting text: \"%s\"\n", Command_TextObject_ToString(&textObject));
 
        // Apply four operations to the text.
        Command_ApplyReplaceCommand(&textObject, "text", "painting");
        Command_ApplyReplaceCommand(&textObject, "on", "off");
        Command_ApplyReverseCommand(&textObject);
        Command_ApplyReplaceCommand(&textObject, "i", "!");
 
        printf("  Now perform undo until back to original\n");
 
        // Now undo the four operations.
        Command_Undo(&textObject);
        Command_Undo(&textObject);
        Command_Undo(&textObject);
        Command_Undo(&textObject);
 
        printf("  Final text   : \"%s\"\n", Command_TextObject_ToString(&textObject));
 
        Command_TextObject_Clear(&textObject);
    }
    printf("  Done.\n");
}

Rust

(Apologies. Doxygen does not understand Rust syntax and therefore cannot colorize the code.)

pub fn command_exercise() -> Result<(), String> {
    println!("");
    println!("Command Exercise");
 
    // Note: The context's undo list owns the commands.  When an undo operation
    // is done, the command is removed from the list and goes away at the end
    // of the undo function.
    let mut command_context = CommandContext::new();
 
    let mut text_object = CommandTextObject::new("This is a line of text on which to experiment.");
 
    println!("  Starting text: \"{text_object}\"");
 
    command_context.apply_replace_command(&mut text_object, "text", "painting");
    command_context.apply_replace_command(&mut text_object, "on", "off");
    command_context.apply_reverse_command(&mut text_object);
    command_context.apply_replace_command(&mut text_object, "i", "!");
 
    println!("  Now perform undo until back to original");
    command_context.undo(&mut text_object);
    command_context.undo(&mut text_object);
    command_context.undo(&mut text_object);
    command_context.undo(&mut text_object);
 
    println!("  Final text   : \"{text_object}\"");
 
    println!("  Done.");
 
    Ok(())
}

See Also

• Main page