What is the standard way of creating new Vim Commands?

Question

I was recently going through a tutorial on configuring the Vimrc file to make it behave more like traditional text editors. In that tutorial, I came across the following line: command! -nargs=* Wrap set wrap linebreak nolist. This has the effect of allowing one to simply type ":Wrap" and activate a number of behaviors.

The problem I have is two-fold. First: is there an easy way to disable these settings (after they have been enabled) with a simple command or do I need to enter something like ":set nowrap nolinebreak list" ? Second, how does that "command!...." work? The tutorial gave no guidance as to how to interpret the mechanics of that line. What does "command!" do? What about "-nargs=*"? I understand everything else methinks... I am still too new to this to find simply reading the documentation to be particularly elucidating and have yet to find a tutorial on the subject.

Answer 1

You've been looking at the documentation for :command without any arguments. The documentation when you are passing arguments is a couple of paragraphs further down. (:h E174 to jump straight there.) The relevant part reads:

If the command already exists, an error is reported, unless a ! is specified, in which case the command is redefined.

The explanation of -nargs is further down still, at :h :command-nargs. It begins:

By default, a user defined command will take no arguments (and an error is reported if any are supplied). However, it is possible to specify that the command can take arguments, using the -nargs attribute. Valid cases are:

-nargs=0 No arguments are allowed (the default)
-nargs=1 Exactly one argument is required, it includes spaces
-nargs=* Any number of arguments are allowed (0, 1, or many), separated by white space

So the command creates a new command named :Wrap which takes any number of arguments. If the :Wrap command already exists, it overwrites it with the new functionality. The :Wrap command ignores all the arguments and sets nowrap, nolinebreak, and list. Your guess is as good as mine as to why the arguments are allowed if they are simply going to be ignored.

(In case you don't know what an "argument" is: it's just words that you type after a command, that the command uses. e.g. when you save a new file with :w <filename>, the file name you type after the :w command is the command's argument.)

You are correct that :set nowrap nolinebreak list would set/unset the options again. If you wanted to write a command that performed the inverse of the one in your question, then you could try simply changing the options:

command! -nargs=* Unwrap set nowrap nolinebreak list