Add clipper#set_invocation()

In response to: wincent/clipper#19 (comment)
wincent · Dec 18, 2018 · 0200f2f · 0200f2f
1 parent 35d15d7
commit 0200f2f
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 10 deletions.
diff --git a/autoload/clipper.vim b/autoload/clipper.vim
@@ -0,0 +1,6 @@
+" Copyright 2018-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+function! clipper#set_invocation(method) abort
+  call clipper#private#set_invocation(a:method)
+endfunction
diff --git a/autoload/clipper/private.vim b/autoload/clipper/private.vim
@@ -1,8 +1,16 @@
 " Copyright 2015-present Greg Hurrell. All rights reserved.
 " Licensed under the terms of the BSD 2-clause license.
 
+function! clipper#private#set_invocation(method) abort
+  if !exists('s:invocation')
+    let s:invocation=a:method
+  endif
+endfunction
+
 function! clipper#private#clip() abort
-  if executable('nc') == 1
+  if exists('s:invocation') && s:invocation != ''
+    call system(s:invocation, @0)
+  elseif executable('nc') == 1
     let l:address = get(g:, 'ClipperAddress', 'localhost')
     let l:port = +(get(g:, 'ClipperPort', 8377)) " Co-erce to number.
     if l:port

diff --git a/doc/clipper.txt b/doc/clipper.txt
@@ -2,15 +2,16 @@
 
 CONTENTS                                                     *clipper-contents*
 
-1. Intro           |clipper-intro|
-2. Installation    |clipper-installation|
-3. Commands        |clipper-commands|
-4. Options         |clipper-options|
-5. Mappings        |clipper-mappings|
-6. Website         |clipper-website|
-7. License         |clipper-license|
-8. Authors         |clipper-authors|
-9. History         |clipper-history|
+ 1. Intro           |clipper-intro|
+ 2. Installation    |clipper-installation|
+ 3. Commands        |clipper-commands|
+ 4. Options         |clipper-options|
+ 5. Functions       |clipper-functions|
+ 6. Mappings        |clipper-mappings|
+ 7. Website         |clipper-website|
+ 8. License         |clipper-license|
+ 9. Authors         |clipper-authors|
+10. History         |clipper-history|
 
 
 INTRO                                                           *clipper-intro*
@@ -73,6 +74,12 @@ OPTIONS                                                       *clipper-options*
   Note that if you want to connect using a UNIX domain socket, you must also
   set |g:ClipperPort| to 0.
 
+  If |g:ClipperAddress| and |g:ClipperPort| provide insufficient
+  configurability (for example, because you are using a version of `nc` that
+  doesn't support UNIX sockets and want to use an alternative like
+  `socat - UNIX-CLIENT:$SOCKET`), then you can use |clipper#set_invocation()|
+  to provide an entirely custom string.
+
                                                                 *g:ClipperPort*
   |g:ClipperPort|                                        number (default: 8377)
 
@@ -84,6 +91,12 @@ OPTIONS                                                       *clipper-options*
   To connect via a UNIX domain socket, set the port number to 0, and provide
   the path to the socket using the |g:ClipperAddress| option.
 
+  If |g:ClipperAddress| and |g:ClipperPort| provide insufficient
+  configurability (for example, because you are using a version of `nc` that
+  doesn't support UNIX sockets and want to use an alternative like
+  `socat - UNIX-CLIENT:$SOCKET`), then you can use |clipper#set_invocation()|
+  to provide an entirely custom string.
+
                                                                 *g:ClipperAuto*
   |g:ClipperAuto|                                          boolean (default: 1)
 
@@ -109,6 +122,32 @@ OPTIONS                                                       *clipper-options*
     let g:ClipperLoaded=1
 
 
+FUNCTIONS                                                   *clipper-functions*
+
+
+  |clipper#set_invocation()|                         *clipper#set_invocation()*
+
+  Provide a completely custom string to invoke an arbitrary executable with
+  arguments. This overrides the automatic invocation that would usually be
+  created using `nc` and the values of |g:ClipperAddress| and |g:ClipperPort|.
+  This may be necessary in environments where you want to use a UNIX domain
+  socket but the local version of `nc` does not support the `-U` switch. For
+  example: >
+
+    call clipper#set_invocation('socat - UNIX-CLIENT:/path/to/socket')
+<
+  Note: This is a function and not a setting for security reasons; only the
+  first call to |clipper#set_invocation()| will have any effect. In this way,
+  you can place the call near the start of your |vimrc| without having to
+  worry that a malicious plug-in will later overwrite it with something
+  nefarious (important because whatever is passed to this function will be
+  blindly executed with the |system()| function).
+
+  As such, even if you don't want to use this feature, it is a good
+  idea to lock it down by calling `clipper#set_invocation('')` in your
+  |vimrc|.
+
+
 MAPPINGS                                                     *clipper-mappings*
 
                                                             *<Plug>ClipperClip*
@@ -178,6 +217,10 @@ vim-clipper is written and maintained by Greg Hurrell <greg@hurrell.net>.
 
 HISTORY                                                       *clipper-history*
 
+master (not yet released)
+
+- Add ability to customize invocation with |clipper#set_invocation()|.
+
 2.0 (25 August 2017)
 
 - Add ability to automatically send yanked text to Clipper using the