what does the number 1 in the shellescape function mean in vim?

Question

A vim command confuses me. I have read and re-read :help shellescape() several times. I still don't understand the meaning of the number 1 in shellescape(expand('%:p'), 1) .

Here's the full command I'm trying to understand:

:nnoremap <F4> :exe ':silent  !"c:\Program Files\Mozilla Firefox\firefox.exe"'shellescape(expand('%:p'), 1)<CR>   

Let's break down this long command piece by piece.

• the command is to map an exe command into F4 in the whole.
• :exe is to execute some command.
• :silent ! is to execute a shell command silently
• "c:\\Program Files\\Mozilla Firefox\\firefox.exe" can call my firefox program.
• shellescape() , there are blanks to be escaped.
• expand('%:p') can get current file name in full expression that is path + filename.

What does this excerpt from the help page mean?

With a |non-zero-arg| {special} and 'shell' containing "csh" in the tail it's
escaped a second time.

Is there some meaning such the same as 1 or 2 in s/(ha.*)(world)/\\2\\1/g ?
please take a simple example in detail.

And i have two questions related to the topic.
1.In which way i can get how many type of shells in my gvim?
2.In which situation can i change 1 into 2 in shellescape()?

:nnoremap <F4> :exe ':silent  !"c:\Program Files\Mozilla Firefox\firefox.exe"'shellescape(expand('%:p'), 2)<CR> 

Answer 1

There are basically two different uses for shellescape() ; one is the Vimscript system() function, the other the :! Ex command. While most escaping needs are identical in both uses (eg to deal with whitespace, arguments must be enclosed in quotes), the :! command requires some additional escaping , because on the command-line, Vim assigns special meaning to symbols like % (replacing it with the current file name). This does not happen for system() .

Therefore, to tell shellescape() which escaping mode to use, it has the additional {special} argument; if you pass 1 (or any other value that evaluates to "true"), the additional characters are escaped, too.

TL;DR: Pass 1 for :! commands, 0 or omit the argument for use with system() .

Answer 2

From the help for shellescape() :

shellescape({string} [, {special}])          shellescape()
    Escape {string} for use as a shell command argument.
    On MS-Windows and MS-DOS, when 'shellslash' is not set, it
    will enclose {string} in double quotes and double all double
    quotes within {string}.
    For other systems, it will enclose {string} in single quotes
    and replace all "'" with "'\''".
    When the {special} argument is present and it's a non-zero
    Number or a non-empty String (non-zero-arg), then special
    items such as "!", "%", "#" and "<cword>" will be preceded by
    a backslash.  This backslash will be removed again by the :!
    command.

The 1 in your example simply tells shellescape() to escape special characters with a backslash. If you were to have (say) a ! in the path returned by expand() , it'd be replaced with \\! .

shell is an option:

                                                    'shell' 'sh' E91
'shell' 'sh'                 string (default $SHELL or "sh",
                                            MS-DOS and Win32: "command.com" or
                                            "cmd.exe", OS/2: "cmd")
                    global
    Name of the shell to use for ! and :! commands.

— :help 'shell'

“ With a non-zero-arg {special} and 'shell' containing "csh" in the tail it's escaped a second time ” means that if, as in your example, shellescape() is given a non-zero argument for special (your example has a 1 ), it will check shell for that "csh" , and if it finds it (if your shell is set to something containing csh ) it will double-escape it.

EDIT to specifically answer two questions added to (edited) original post:

1. You can get your shell setting (referred to in the shellescape() help quote) using :echo &shell .

2. 2 is a Number and is non-zero. You should therefore be able to substitute 2 for the 1 in your example and get the same result.