Definition  : (object) PARSE_COMMAND_ONE( str, invenv, pattern )

Defined in  : <cmdparse.h>

Description : Based on the PARSE_COMMAND() macro, this macro does the same but
              only returns exactly one object, or it returns nothing. This is
	      especially useful when you want your command to operate on a
	      single item. Even if 2 or more were found, it will not return
	      the item. You can use PARSE_COMMAND_SIZE to find out how many
	      items were found to give a proper message.

Arguments   : See "man PARSE_COMMAND".

Returns     : object - the object that matched, or 0.

Example     : Find a single object in the player's inventory or environment.

    object target;
    target = PARSE_COMMAND_ONE(str, 0, "[the] %i");
    if (!objectp(target))
    {
        notify_fail(capitalize(query_verb()) + " what?" +
            (PARSE_COMMAND_SIZE ? " Please select only one item." : "") + "\n");
        return 0;
    }

See also    : parse_command, PARSE_COMMAND and PARSE_COMMAND_SIZE
