clipboard 1.4.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1176250dac08a0b34135139cae0057d85980a5db1b64f56b5c89fd4745d176e2
-  data.tar.gz: b55213775852ec00ffa7d58a8e97b8e3b31530067e02e6604885873e44a6424e
+  metadata.gz: 26af5bebb02475904f8047927426e95fd93f85f2e6d1621f1caf1b36ae162416
+  data.tar.gz: bea335752871a978d4eaf1897bcc86846d81d6d6a8b4104dc90dcec8ec367333
 SHA512:
-  metadata.gz: 317ce477428ad9390f5ea8dff8afac8fbd23633210bc94de5a4f5db55982681e1a6fa7c4eca2c2204ca4d46238a707ec1a5516076fa456556ad0ec0bd1b7221e
-  data.tar.gz: f7245a4588ba5fecfd2974f970b6849807fe488acc321b54d546c993900c95487b2be5c0bf50230ba617fa3aac15097ffc912050fdbe1cf2983be41321b6b976
+  metadata.gz: c01a2858756e7cf11f46fb6dd12a4913bb5cb2a0c267b74f650acef1410775de5130a865fe6ee06114e6a76c455d7545c7587bbdefa9eda3013c90b304b296d7
+  data.tar.gz: c4b021d55aaa8f93491fcb805749a6041950a6ffdb8891e707ac1e91271fdcc7c6e6f94ec8eda0cd745b6f93515ef17e592c7149b120d072db6573e4237d2408

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # CHANGELOG
 
+## 2.0.0
+
+### Major Changes
+* Requires Ruby 3.0
+* `Clipboard.copy` and `.clear` now always return true instead of the pasted string
+
+### New Features
+* Add experimental OSC52 implementation (only `Clipboard.copy`)
+* Linux-based `Clipboard.copy` methods now take a clipboard argument `clipboard:`
+  to choose which clipboard to copy to (default is "all").
+  For example: `Clipboard.copy("data", clipboard: "primary")` copies only to primary clipboard
+* Linux-based `Clipboard.paste` methods use either the `clipboard:` keyword argument or the
+  single positional argument for choosing the clipboard to paste from
+* Allow setting the clipboard implementation with snake-cased symbol/string:
+  `Clipboard.implementation = :linux_wayland`
+
+### Refactorings / Minor API Changes
+* Change `copy`, `paste`, and `clear` to always accept keyword arguments
+* All implementations are now based on `Clipboard::Implementation`
+* Move implementation detection to `utils.rb`
+* Be sure to pass a valid lowercase clipboard selection name (or `"all"`) when choosing clipboards,
+  it will now raise an `ArgumentError` if the clipboard name is not supported by the implementation
+
+### Other
+* Add more specs and run them on GitHub Actions CI
+
 ## 1.4.1
 * Always use plaintext mimetype for wl-clipboard
 * Do not include newline when pasting from wl-clipboard

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'ffi', platforms: [:mingw, :mswin, :x64_mingw]

data/README.md

@@ -1,6 +1,6 @@
-# Clipboard Ruby Gem [![version](https://badge.fury.io/rb/clipboard.svg)](https://badge.fury.io/rb/clipboard) [![[ci]](https://github.com/janlelis/clipboard/workflows/Test/badge.svg)](https://github.com/janlelis/clipboard/actions?query=workflow%3ATest)
+# Clipboard Ruby Gem 📋︎ [![version](https://badge.fury.io/rb/clipboard.svg)](https://badge.fury.io/rb/clipboard) [![[ci]](https://github.com/janlelis/clipboard/workflows/Test/badge.svg)](https://github.com/janlelis/clipboard/actions?query=workflow%3ATest)
 
-Lets you access the clipboard from everywhere. Currently supported platforms:
+Lets you access the system clipboard from everywhere. Currently supported platforms:
 
 - Linux (X11)
 - Linux (Wayland)
@@ -10,10 +10,11 @@ Lets you access the clipboard from everywhere. Currently supported platforms:
 - WSL (Windows Subsystem for Linux)
 - Gtk+ (Cross Platform Widget Toolkit)
 - Java (on JRuby)
+- *Experimental:* OSC52 (ANSI escape sequence) **only copying** - see note below
 
 Supported Rubies: **3.3**, **3.2**, **3.1**, **3.0**
 
-Unsupported, but might still work: **2.X**
+Unsupported, but might still work: **2.X** (use clipboard gem version 1.x)
 
 ## Usage
 
@@ -23,51 +24,73 @@ Unsupported, but might still work: **2.X**
 
 ## Setup
 
-Add the following lines to your `Gemfile`:
+Run `gem install clipboard` (and `gem install ffi` on Windows) or add the following lines to your `Gemfile`:
 
 ```ruby
 gem "clipboard"
-gem "ffi", :platforms => [:mswin, :mingw] # Required by Clipboard on Windows
+gem "ffi", :platforms => [:mswin, :mingw] # Necessary on Windows
 ```
 
-- **Important note for Linux** users: The clipboard requires the *xsel* or the *xclip* command-line program (X11), or the *wl-copy* / *wl-paste* command-line programs (Wayland). On debian and ubuntu, *xsel* can be installed with: `sudo apt-get install xsel` and *wl-copy* / *wl-paste* with `sudo apt-get install wl-clipboard`.
+**Important note for Linux** users: The clipboard gem requires additional programs to be available:
+
+- On X11: **xsel** or **xclip**
+- On Wayland: **wl-copy** and **wl-paste** (wl-clipboard) - depending on your system, just having **xsel** / **xclip** might also work
+
 
 ## Clipboard Implementations
 
 In most environments, the appropriate clipboard implementation can be detected automatically. If none is found, the gem will fallback to a file based one, which will just write to/read from `~/.clipboard` instead of the system clipboard.
 
-You can check the implementation used with: `Clipboard.implementation`
+You can check the implementation used with `Clipboard.implementation` or set a specific implementation with `Clipboard.implementation = ...`
 
 ### Alternative Clipboard Providers
 
-There are two implementations included in this gem, which are not used by default. You can opt-in to use them if you think they are a better fit for your application environment:
+There are more implementations included in this gem, which are not activated by default. You can opt-in to use them if you think they are a better fit for your application environment:
 
 #### Java
 
-Activate with: `Clipboard.implementation = Clipboard::Java`
+Activate with: `Clipboard.implementation = :java`
 
 This is an option for [JRuby users](https://www.jruby.org/) which will use the clipboard functionality from the Java standard library.
 
 #### GTK+
 
-Activate with: `Clipboard.implementation = Clipboard::Gtk`
+Activate with: `Clipboard.implementation = :gtk`
 
 This utilizes the **GTK+** library. See [Ruby-GNOME2](https://github.com/ruby-gnome2/ruby-gnome2#ruby-gnome2) for more info.
 
 Requires the `gtk3` or `gtk2` gem to be installed.
 
+#### OSC52
+
+Activate with: `Clipboard.implementation = :osc52`
+
+OSC52 is an ANSI escape sequence that some terminals support to access the system clipboard. One advantage of using this clipboard proider is that it is possible to copy from remote ssh sessions to your system clipboard.
+
+As of the current version, only **copy** and **clear** commands are supported (no **paste**).
+
+**Please note**: Even if your terminal includes OSC52 functionality, the feature could be (partially) disabled to prevent malicious scripts from accessing (or setting) your clipboard.
+
 ## Tips & Tricks
 
 ### Linux: Using Clipboard via SSH
 
-To be able to use the clipboard through SSH, you need to install `xauth` on your server and connect via `ssh -X` or `ssh -Y`. Please note that some server settings restrict this feature.
+To be able to use the clipboard through SSH (using the `xsel`/`xclip` based implementation), you need to install `xauth` on your server and connect via `ssh -X` or `ssh -Y`. Please note that some server settings restrict this feature.
+
+### Linux: Copy To or Paste From Specific Clipboard / Selection
 
-### Linux: Paste From Specific X11 Selection
+The clipboard on Linux is divided into multiple clipboard selections. You can choose from which clipboard you want to `paste` from by passing it as the first argument. The default is *:clipboard*, other options are *:primary* and, for some implementations, *:secondary*:
 
-The clipboard on Linux is divided into multiple clipboard selections. You can choose from which clipboard you want to `paste` from by
-passing it as an argument. The default is *:clipboard*, other options are *:primary* and *:secondary*.
+```ruby
+Clipboard.paste("primary") # or
+Clipboard.paste(clipboard: "primary")
+```
 
-`Clipboard.copy` always copies to all three clipboards.
+`Clipboard.copy` will copy to all available clipboards, except if you specifiy a clipboard using the `clipboard:` keyword argument:
+
+```ruby
+Clipboard.copy("only goes to primary clipboard", clipboard: "primary")
+```
 
 ### Windows: Encoding Info
 
@@ -79,7 +102,7 @@ Clipboard.paste.encode('UTF-8')
 
 ### CLI Utility: blip
 
-The [blip gem]((https://gist.github.com/janlelis/781835)) is a handy command-line wrapper for the clipboard gem. It lets you quickly copy file content to your clipboard:
+The [blip gem](https://rubygems.org/gems/blip) is a handy command-line wrapper for the clipboard gem. It lets you quickly copy a file's content to your clipboard:
 
 ```
 $ blip FILE_NAME
@@ -87,14 +110,6 @@ $ blip FILE_NAME
 
 Without any arguments, it will just paste the contents of the clipboard.
 
-## Further Development
-
-This is a list of nice-to-have features - feel free to open a PR or let me know if you want to work on one of these:
-
-- Native support for clipboard on X11 or Wayland
-- Support more platforms
-- Support clipboard meta data
-
 ## MIT
 
 Copyright (c) 2010-2024 Jan Lelis <https://janlelis.com> released under the MIT license. Contributions by and thanks to [Michael Grosser and all the other contributors!](https://github.com/janlelis/clipboard/graphs/contributors)

data/Rakefile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# # #
+# Get gemspec info
+
+gemspec_file = Dir['*.gemspec'].first
+gemspec = eval File.read(gemspec_file), binding, gemspec_file
+info = "#{gemspec.name} | #{gemspec.version} | " \
+       "#{gemspec.runtime_dependencies.size} dependencies | " \
+       "#{gemspec.files.size} files"
+
+# # #
+# Gem build and install task
+
+desc info
+task :gem do
+  puts info + "\n\n"
+  print "  "; sh "gem build #{gemspec_file}"
+  FileUtils.mkdir_p 'pkg'
+  FileUtils.mv "#{gemspec.name}-#{gemspec.version}.gem", 'pkg'
+  puts; sh %{gem install --no-document pkg/#{gemspec.name}-#{gemspec.version}.gem}
+end
+
+# # #
+# Start an IRB session with the gem loaded
+
+desc "#{gemspec.name} | IRB"
+task :irb do
+  sh "irb -I ./lib -r #{gemspec.name.tr '-', '/'}"
+end
+
+# # #
+# Run Specs
+
+desc "#{gemspec.name} | Spec"
+task :spec do
+  sh "rspec"
+end
+task default: :spec

data/clipboard.gemspec

@@ -1,27 +1,28 @@
 # frozen_string_literal: true
 
-$:.unshift File.expand_path("../lib", __FILE__)
-require 'clipboard/version'
+require_relative 'lib/clipboard/version'
 
 Gem::Specification.new do |s|
   s.name     = 'clipboard'
   s.version  = Clipboard::VERSION
   s.authors  = ["Jan Lelis"]
   s.email    = ["hi@ruby.consulting"]
-  s.summary  = "Access to the clipboard on Linux, MacOS, Windows, and Cygwin."
-  s.description = "Access to the clipboard on Linux, MacOS, Windows, and Cygwin: Clipboard.copy, Clipboard.paste, Clipboard.clear"
+  s.summary  = "Access the system clipboard 📋︎ on Linux, MacOS, Windows, WSL, Cygwin, GTK, or Java."
+  s.description = "Access the system clipboard 📋︎ on Linux, MacOS, Windows, WSL, Cygwin, GTK, or Java. Usage is as simple as calling Clipboard.copy or Clipboard.paste!"
   s.homepage = "https://github.com/janlelis/clipboard"
   s.license  = "MIT"
   s.metadata = { "rubygems_mfa_required" => "true" }
   s.requirements = [
-    "Linux: You need xclip / xsel (X11) or wl-clipboard (Wayland)",
-    "Windows: You need the ffi gem",
+    "Linux-X11: xclip or xsel",
+    "Linux-Wayland: wl-clipboard",
+    "Windows: ffi gem",
   ]
-  s.files = Dir.glob(%w[{lib,spec}/**/*.rb [A-Z]*.txt [A-Z]*.md]) + %w{clipboard.gemspec}
+  s.files = Dir.glob(%w[{lib,spec}/**/*.rb [A-Z]*.txt [A-Z]*.md]) + %w[clipboard.gemspec Gemfile Rakefile]
 
-  s.required_ruby_version = '>= 1.9.3'
-  s.add_development_dependency 'rake', '~> 13.0'
+  s.required_ruby_version = '>= 3.0'
+  s.add_development_dependency 'rake', '~> 13.2'
   s.add_development_dependency 'rspec', '~> 3'
+  s.add_development_dependency 'rubocop', '~> 1.6'
   # s.add_development_dependency 'ffi', '~> 1.9'
   # s.add_development_dependency 'gtk3', '~> 3'
 end

data/lib/clipboard/clipboard_load_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Clipboard
+  class ClipboardLoadError < StandardError
+  end
+end

data/lib/clipboard/cygwin.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
+
 module Clipboard
   module Cygwin
+    include Implementation
     extend self
 
-    def paste(_ = nil)
+    def paste(_ = nil, **)
       ::File.read("/dev/clipboard")
     end
 
-    def copy(data)
+    def copy(data, **)
       ::File.open("/dev/clipboard", "w"){ |f| f.write(data) }
-      paste
-    end
 
-    def clear
-      copy ''
+      true
     end
   end
 end

data/lib/clipboard/file.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
+
 module Clipboard
   module File
+    include Implementation
     extend self
 
     FILE = ::File.expand_path("~/.clipboard")
 
-    def copy(text)
-      ::File.open(FILE, 'w', 0o0600) { |f| f.write(text) } rescue ''
-      paste
-    end
+    def copy(data, **)
+      ::File.open(FILE, 'w', 0o0600) { |f| f.write(data) } rescue ''
 
-    def paste(_ = nil)
-      ::File.read(FILE) rescue ''
+      true
     end
 
-    def clear
-      copy ''
+    def paste(_ = nil, **)
+      ::File.read(FILE) rescue ''
     end
   end
 end

data/lib/clipboard/gtk.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-# Ruby-Gnome2 based implementation
-# Requires either the gtk3 or the gtk2 gem
+require_relative "implementation"
 
 module Clipboard
+  # Ruby-Gnome2 based implementation
+  # Requires either the gtk3 or the gtk2 gem
   module Gtk
+    include Implementation
     extend self
 
-    CLIPBOARDS = %w[CLIPBOARD PRIMARY SECONDARY].freeze
+    CLIPBOARDS = %w[clipboard primary secondary].freeze
 
     unless defined? ::Gtk
       begin
@@ -21,27 +23,35 @@ module Clipboard
       end
     end
 
-    def copy(text)
-      CLIPBOARDS.each{ |which|
-        ::Gtk::Clipboard.get(Gdk::Selection.const_get(which)).set_text(text).store
-      }
-      paste
-    end
-
-    def paste(which = nil)
-      if !which || !CLIPBOARDS.include?(which_normalized = which.to_s.upcase)
-        which_normalized = CLIPBOARDS.first
-      end
+    def paste(which = nil, clipboard: "clipboard")
+      selection = which || clipboard
+      raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
 
       ::Gtk::Clipboard.get(
-        Gdk::Selection.const_get(which_normalized)
+        Gdk::Selection.const_get(selection.to_s.upcase)
       ).wait_for_text || ""
     end
 
-    def clear
-      CLIPBOARDS.each{ |which|
-        ::Gtk::Clipboard.get(Gdk::Selection.const_get(which)).clear
+    def copy(data, clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        ::Gtk::Clipboard.get(Gdk::Selection.const_get(selection.to_s.upcase)).set_text(data).store
       }
+
+      true
+    end
+
+    def clear(clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        ::Gtk::Clipboard.get(Gdk::Selection.const_get(selection.to_s.upcase)).clear
+      }
+
+      true
     end
   end
 end

data/lib/clipboard/implementation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Clipboard
+  module Implementation
+    extend self
+
+    # Implement paste
+    # Should take an optional argument
+    def paste(_clipboard_name = nil, **)
+      raise NotImplementedError, "pasting not supported by this implementation, try another"
+    end
+
+    # Takes the data to copy as argument
+    # Should return true
+    def copy(_data, **)
+      raise NotImplementedError, "copying not supported by this implementation, try another"
+    end
+
+    # Can be used to add a native clear implementation
+    # Should return true
+    def clear(**kwargs)
+      copy('', **kwargs)
+
+      true
+    end
+  end
+end

data/lib/clipboard/java.rb

@@ -1,26 +1,26 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
+
 module Clipboard
   # Basic java clipboard access (jruby). No fun to use on X.
   module Java
+    include Implementation
     extend self
 
     FLAVOR = ::Java::JavaAwtDatatransfer::DataFlavor.stringFlavor
 
-    def copy(text)
-      selection_string = ::Java::JavaAwtDatatransfer::StringSelection.new text
+    def copy(data, **)
+      selection_string = ::Java::JavaAwtDatatransfer::StringSelection.new data
       ::Java::JavaAwt::Toolkit.default_toolkit.system_clipboard.set_contents selection_string, nil
-      paste
+
+      true
     end
 
-    def paste(_ = nil)
+    def paste(_ = nil, **)
       ::Java::JavaAwt::Toolkit.default_toolkit.system_clipboard.get_data(FLAVOR)
     rescue
       ''
     end
-
-    def clear
-      copy ''
-    end
   end
 end

data/lib/clipboard/linux.rb

@@ -1,52 +1,55 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
 require_relative "utils"
 
 module Clipboard
   module Linux
+    include Implementation
     extend self
 
     CLIPBOARDS = %w[clipboard primary secondary].freeze
 
-    # check which backend to use
+    # First check for xsel, fallback to xclip
     if Utils.executable_installed? "xsel"
-      WriteCommand = 'xsel -i'
-      ReadCommand  = 'xsel -o'
-      ReadOutputStream = true
-      Selection    = {
-        'clipboard' => '-b',
-        'primary' => '-p',
-        'secondary' => '-s'
+      WRITE_COMMAND = 'xsel -i'
+      READ_COMMAND = 'xsel -o'
+      READ_OUTPUT_STREAM = true
+      SELECTION = {
+        'clipboard' => '--clipboard',
+        'primary' => '--primary',
+        'secondary' => '--secondary'
       }.freeze
+
     elsif Utils.executable_installed? "xclip"
-      WriteCommand = 'xclip'
-      ReadCommand  = 'xclip -o'
-      ReadOutputStream = false
-      Selection    = proc{ |x|
+      WRITE_COMMAND = 'xclip'
+      READ_COMMAND = 'xclip -o'
+      READ_OUTPUT_STREAM = false
+      SELECTION = proc{ |x|
         "-selection #{x}"
       }.freeze
+
     else
-      raise Clipboard::ClipboardLoadError, "clipboard: Could not find required program xclip or xsel\n" \
-                                           "On debian/ubuntu, you can install it with: sudo apt-get install xsel\n" \
-                                           "If your system is Wayland-based, please install wl-clipboard"
+      raise Clipboard::ClipboardLoadError,
+            "clipboard: Could not find required program xsl or xclip (X11) or wl-clipboard (Wayland)"
     end
 
-    def paste(which = nil)
-      if !which || !CLIPBOARDS.include?(which_normalized = which.to_s.downcase)
-        which_normalized = CLIPBOARDS.first
-      end
-      `#{ReadCommand} #{Selection[which_normalized]} 2> /dev/null`
-    end
+    def paste(which = nil, clipboard: "clipboard")
+      selection = which || clipboard
+      raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
 
-    def clear
-      copy ''
+      `#{READ_COMMAND} #{SELECTION[selection]} 2> /dev/null`
     end
 
-    def copy(data)
-      CLIPBOARDS.each{ |which|
-        Utils.popen "#{WriteCommand} #{Selection[which]}", data, ReadOutputStream
+    def copy(data, clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        Utils.popen "#{WRITE_COMMAND} #{SELECTION[selection]}", data, READ_OUTPUT_STREAM
       }
-      paste
+
+      true
     end
   end
 end

data/lib/clipboard/linux_wayland.rb

@@ -1,35 +1,55 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
 require_relative "utils"
 
 module Clipboard
   module LinuxWayland
+    include Implementation
     extend self
 
+    CLIPBOARDS = %w[clipboard primary].freeze
+
     TEST_COMMAND  = "wl-copy"
     WRITE_COMMAND = "wl-copy --type text/plain"
     READ_COMMAND  = "wl-paste --type text/plain --no-newline"
 
     if !Utils.executable_installed?(TEST_COMMAND)
-      raise Clipboard::ClipboardLoadError, "clipboard: Could not find required program wl-copy\n" \
-                                           "Please install it or try a different implementation"
+      raise Clipboard::ClipboardLoadError,
+            "clipboard: Could not find required program wl-clipboard"
     end
 
-    def paste(might_select_primary_clipboard = nil)
-      if might_select_primary_clipboard == "primary"
-        `#{READ_COMMAND} --primary`
-      else
-        `#{READ_COMMAND}`
-      end
+    def paste(which = nil, clipboard: "clipboard")
+      selection = which || clipboard
+      raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+      primary_flag = selection == "primary" ? " --primary" : ""
+
+      `#{READ_COMMAND}#{primary_flag}`
     end
 
-    def copy(data)
-      Utils.popen WRITE_COMMAND, data
-      paste
+    def copy(data, clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        primary_flag = selection == "primary" ? " --primary" : ""
+        Utils.popen("#{WRITE_COMMAND}#{primary_flag}", data)
+      }
+
+      true
     end
 
-    def clear
-      `#{WRITE_COMMAND} --clear`
+    def clear(clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        primary_flag = selection.to_s == "primary" ? " --primary" : ""
+        `#{WRITE_COMMAND}#{primary_flag} --clear`
+      }
+
+      true
     end
   end
 end

data/lib/clipboard/mac.rb

@@ -1,22 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
 require_relative "utils"
 
 module Clipboard
   module Mac
+    include Implementation
     extend self
 
-    def paste(_ = nil)
+    def paste(_ = nil, **)
       `pbpaste`
     end
 
-    def copy(data)
+    def copy(data, **)
       Utils.popen "pbcopy", data
-      paste
-    end
 
-    def clear
-      copy ''
+      true
     end
   end
 end

data/lib/clipboard/osc52.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "implementation"
+
+module Clipboard
+  module Osc52
+    include Implementation
+    extend self
+
+    CLIPBOARDS = %w[clipboard primary].freeze
+    OSC52 = "]52;%<selection_option>s;%<data_base64>s"
+
+    def copy(data, clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        print OSC52 % {
+          selection_option: selection == "primary" ? "p" : "c",
+          data_base64: [data].pack("m0"),
+        }
+      }
+
+      true
+    end
+
+    def clear(clipboard: "all")
+      selections = clipboard.to_s == "all" ? CLIPBOARDS : [clipboard]
+      selections.each{ |selection|
+        raise ArgumentError, "unknown clipboard selection" unless CLIPBOARDS.include?(selection)
+
+        print OSC52 % {
+          selection_option: selection == "primary" ? "p" : "c",
+          data_base64: ?! # anything non-base64 / question mark clears
+        }
+      }
+
+      true
+    end
+  end
+end

data/lib/clipboard/utils.rb

@@ -1,11 +1,40 @@
 # frozen_string_literal: true
 
+require "rbconfig"
 require "open3"
 
+require_relative "clipboard_load_error"
+
 module Clipboard
   module Utils
     extend self
 
+    # Find out which implementation is best to use
+    def autodetect_implementation
+      os = case RbConfig::CONFIG['host_os']
+      when /mac|darwin/        then :Mac
+      when /linux|bsd/         then :Linux
+      when /mswin|mingw/       then :Windows
+      when /cygwin/            then :Cygwin
+      else
+        raise ClipboardLoadError, "clipboard: Could not find suitable implementation for OS(#{ RbConfig::CONFIG['host_os'] })"
+      end
+
+      # Running additional check to detect if running in Microsoft WSL or Wayland
+      if os == :Linux
+        require "etc"
+        if Etc.uname[:release] =~ /Microsoft/
+          os = :Wsl
+        # Only choose Wayland implementation if wl-copy is found, since xclip / xsel *might* work
+        elsif ENV["XDG_SESSION_TYPE"] == "wayland" && executable_installed?("wl-copy")
+          os = :LinuxWayland
+        end
+      end
+
+      os
+    end
+
+    # Check if a necessary command is available
     def executable_installed?(cmd)
       ENV['PATH'].split(::File::PATH_SEPARATOR).any? do |path|
         ::File.executable?(::File.join(path, cmd))

data/lib/clipboard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clipboard
-  VERSION = "1.4.1"
+  VERSION = "2.0.0"
 end

data/lib/clipboard/windows.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-require_relative 'utils'
+require_relative "implementation"
+require_relative "utils"
 
 module Clipboard
   module Windows
+    include Implementation
     extend self
 
     CF_TEXT = 1
@@ -41,7 +43,7 @@ module Clipboard
     end
 
     # see http://www.codeproject.com/KB/clipboard/archerclipboard1.aspx
-    def paste(_ = nil)
+    def paste(_ = nil, **)
       return String.new unless User32.open(nil)
 
       hclip = User32.get( CF_UNICODETEXT )
@@ -57,14 +59,15 @@ module Clipboard
       User32.close
     end
 
-    def clear
+    def clear(**)
       User32.empty if User32.open(nil)
-      paste
+
+      true
     ensure
       User32.close
     end
 
-    def copy(data_to_copy)
+    def copy(data_to_copy, **)
       if User32.open(nil)
         User32.empty
         data = data_to_copy.encode(Encoding::UTF_16LE) # TODO: catch bad encodings
@@ -77,11 +80,11 @@ module Clipboard
           Kernel32.unlock( handler )
         end
         User32.set( CF_UNICODETEXT, handler )
-        data.chop
       else # don't touch anything
         Utils.popen "clip", data_to_copy # depends on clip (available by default since Vista)
-        paste
       end
+
+      true
     ensure
       User32.close
     end

data/lib/clipboard/wsl.rb

@@ -1,22 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "implementation"
 require_relative "utils"
 
 module Clipboard
   module Wsl
+    include Implementation
     extend self
 
-    def paste(_ = nil)
+    def paste(_ = nil, **)
       `powershell.exe -Command Get-Clipboard`
     end
 
-    def copy(data)
+    def copy(data, **)
       Utils.popen "clip.exe", data
-      paste
-    end
 
-    def clear
-      copy ''
+      true
     end
   end
 end

data/lib/clipboard.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-require 'rbconfig'
-
 require_relative 'clipboard/version'
 require_relative 'clipboard/utils'
+require_relative 'clipboard/clipboard_load_error'
 
 module Clipboard
   extend self
 
-  class ClipboardLoadError < StandardError
-  end
-
   unless defined? Ocra # see gh#9
     autoload :Linux,          'clipboard/linux'
     autoload :LinuxWayland,   'clipboard/linux_wayland'
@@ -19,6 +15,7 @@ module Clipboard
     autoload :Cygwin,         'clipboard/cygwin'
     autoload :Wsl,            'clipboard/wsl'
     autoload :Gtk,            'clipboard/gtk'
+    autoload :Osc52,          'clipboard/osc52'
   end
   autoload :Windows, 'clipboard/windows'
   autoload :File,    'clipboard/file'
@@ -26,46 +23,36 @@ module Clipboard
   def self.implementation
     return @implementation if @implementation
 
-    os = case RbConfig::CONFIG['host_os']
-    when /mac|darwin/        then :Mac
-    when /linux|bsd/         then :Linux
-    when /mswin|mingw/       then :Windows
-    when /cygwin/            then :Cygwin
-    else
-      raise ClipboardLoadError, "Your OS(#{ RbConfig::CONFIG['host_os'] }) is not supported"
-    end
-
-    # Running additional check to detect if running in Microsoft WSL or Wayland
-    if os == :Linux
-      require "etc"
-      if Etc.respond_to?(:uname) && Etc.uname[:release] =~ /Microsoft/ # uname was added in ruby 2.2
-        os = :Wsl
-      # Only choose Wayland implementation if wl-copy is found, since xclip / xsel *might* work
-      elsif ENV["XDG_SESSION_TYPE"] == "wayland" && Utils.executable_installed?("wl-copy")
-        os = :LinuxWayland
-      end
-    end
-
-    @implementation = Clipboard.const_get(os)
-  rescue ClipboardLoadError => e
+    @implementation = Clipboard.const_get(Utils.autodetect_implementation)
+  rescue ClipboardLoadError, NameError => e
     $stderr.puts "#{e.message}\nUsing file-based (fake) clipboard" unless $VERBOSE == nil
     @implementation = Clipboard::File
   end
 
-  def self.implementation=(val)
-    @implementation = val
+  def self.implementation=(implementation)
+    if !implementation
+      @implementation = nil
+    elsif implementation.is_a? Module
+      @implementation = implementation
+    else
+      camel_cased_implementation_name = implementation.to_s.gsub(/(?:^|_)([a-z])/) do $1.upcase end
+      @implementation = Clipboard.const_get(camel_cased_implementation_name)
+    end
+  rescue ClipboardLoadError, NameError => e
+    $stderr.puts "#{e.message}\nUsing file-based (fake) clipboard" unless $VERBOSE == nil
+    @implementation = Clipboard::File
   end
 
-  def paste(*args)
-    Clipboard.implementation.paste(*args)
+  def paste(...)
+    Clipboard.implementation.paste(...)
   end
 
-  def clear(*args)
-    Clipboard.implementation.clear(*args)
+  def clear(...)
+    Clipboard.implementation.clear(...)
   end
 
-  def copy(*args)
-    Clipboard.implementation.copy(*args)
+  def copy(...)
+    Clipboard.implementation.copy(...)
   end
 end
 

data/spec/clipboard_file_spec.rb

@@ -2,6 +2,7 @@
 
 require_relative "spec_helper"
 
+require 'clipboard/file'
 require "fileutils"
 
 describe 'Clipboard::File' do
@@ -16,12 +17,13 @@ describe 'Clipboard::File' do
   end
 
   it "can copy & paste" do
-    expect( Clipboard.copy('xxx') ).to eq 'xxx'
-    expect( Clipboard.paste ).to eq 'xxx'
+    Clipboard.copy('123file')
+    expect( Clipboard.paste ).to eq '123file'
   end
 
   it "can clear" do
-    expect( Clipboard.copy('xxx') ).to eq 'xxx'
+    Clipboard.copy('123file')
+    expect( Clipboard.paste ).to eq '123file'
     Clipboard.clear
     expect( Clipboard.paste ).to eq ''
   end

data/spec/clipboard_java_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+if RUBY_ENGINE === "jruby"
+  require 'clipboard/java'
+
+  describe "Clipboard::Java" do
+    before :all do
+      Clipboard.implementation = Clipboard::Java
+    end
+
+    it "can copy & paste" do
+      Clipboard.copy('123java')
+      expect( Clipboard.paste ).to eq '123java'
+    end
+
+    it "can clear" do
+      Clipboard.copy('123java')
+      expect( Clipboard.paste ).to eq '123java'
+      Clipboard.clear
+      expect( Clipboard.paste ).to eq ''
+    end
+  end
+end

data/spec/clipboard_linux_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+require "rbconfig"
+
+if RbConfig::CONFIG['host_os'] =~ /linux|bsd/
+  require 'clipboard/linux'
+
+  describe "Clipboard::Linux" do
+    before :all do
+      Clipboard.implementation = Clipboard::Linux
+    end
+
+    it "can copy & paste" do
+      Clipboard.copy('123linux')
+      expect( Clipboard.paste ).to eq '123linux'
+    end
+
+    it "can clear" do
+      Clipboard.copy('123linux')
+      expect( Clipboard.paste ).to eq '123linux'
+      Clipboard.clear
+      expect( Clipboard.paste ).to eq ''
+    end
+  end
+end

data/spec/clipboard_linux_wayland_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+require "rbconfig"
+
+if RbConfig::CONFIG['host_os'] =~ /linux|bsd/ &&
+   ENV["XDG_SESSION_TYPE"] == "wayland" &&
+   Clipboard::Utils.executable_installed?("wl-copy")
+  require 'clipboard/linux_wayland'
+
+  describe "Clipboard::LinuxWayland" do
+    before :all do
+      Clipboard.implementation = Clipboard::LinuxWayland
+    end
+
+    it "can copy & paste" do
+      Clipboard.copy('123wayland')
+      expect( Clipboard.paste ).to eq '123wayland'
+    end
+
+    it "can clear" do
+      Clipboard.copy('123wayland')
+      expect( Clipboard.paste ).to eq '123wayland'
+      Clipboard.clear
+      expect( Clipboard.paste ).to eq ''
+    end
+  end
+end

data/spec/clipboard_mac_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+require "rbconfig"
+
+if RbConfig::CONFIG['host_os'] =~ /mac|darwin/
+  require 'clipboard/mac'
+
+  describe "Clipboard::Mac" do
+    before :all do
+      Clipboard.implementation = Clipboard::Mac
+    end
+
+    it "can copy & paste" do
+      Clipboard.copy('123mac')
+      expect( Clipboard.paste ).to eq '123mac'
+    end
+
+    it "can clear" do
+      Clipboard.copy('123mac')
+      expect( Clipboard.paste ).to eq '123mac'
+      Clipboard.clear
+      expect( Clipboard.paste ).to eq ''
+    end
+  end
+end

data/spec/clipboard_spec.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-# Please note: cannot test, if it really accesses your platform clipboard.
-
 require_relative "spec_helper"
 
 os_to_restore = RbConfig::CONFIG['host_os']
 
 describe Clipboard do
+  before :all do
+    Clipboard.implementation = Clipboard::Utils.autodetect_implementation
+  end
+
   before do
     RbConfig::CONFIG['host_os'] = os_to_restore
     @is_windows = Clipboard.implementation.name == 'Clipboard::Windows'
@@ -14,10 +16,6 @@ describe Clipboard do
 
   let(:expected) { ->(text) { @is_windows ? text.encode(Encoding::UTF_16LE) : text } }
 
-  it "has a VERSION" do
-    expect( Clipboard::VERSION ).to match /^\d+\.\d+\.\d+$/
-  end
-
   it "can copy & paste" do
     text = "FOO\nBAR"
     Clipboard.copy(text)
@@ -31,14 +29,14 @@ describe Clipboard do
     expect( Clipboard.paste ).to eq expected.(text)
   end
 
-  it "returns data on copy" do
+  it "returns true on copy" do
     text = 'xxx'
-    expect( Clipboard.copy(text) ).to eq expected.(text)
+    expect( Clipboard.copy(text) ).to eq true
   end
 
   it "can clear" do
     Clipboard.copy('xxx')
-    Clipboard.clear
+    expect( Clipboard.clear ).to eq true
     expect( Clipboard.paste ).to eq expected.('')
   end
 
@@ -50,7 +48,7 @@ describe Clipboard do
     it "can copy & paste & clear" do
       a = A.new
       text = 'XXX'
-      expect( a.send(:copy, text) ).to eq expected.(text)
+      expect( a.send(:copy, text) ).to eq true
       expect( a.send(:paste) ).to eq expected.(text)
       a.send(:clear)
       expect( a.send(:paste) ).to eq expected.('')
@@ -61,13 +59,15 @@ describe Clipboard do
   it "can copy more than 8192 bytes" do
     # first batch
     data1 = Random.new.bytes(2**14).unpack("H*").first
-    data2 = Clipboard.copy(data1)
+    Clipboard.copy(data1)
+    data2 = Clipboard.paste
 
     expect(data2).to eq expected.(data1)
 
     # second batch
     data1 = Random.new.bytes(2**14).unpack("H*").first
-    data2 = Clipboard.copy(data1)
+    Clipboard.copy(data1)
+    data2 = Clipboard.paste
 
     expect(data2).to eq expected.(data1)
   end
@@ -98,5 +98,18 @@ describe Clipboard do
       expect( $stderr ).not_to receive(:puts)
       Clipboard.implementation
     end
+
+    it "is possible to set implementation with snake-cased string" do
+      module Clipboard::TestImplementation
+      end
+      Clipboard.implementation = "test_implementation"
+      expect( Clipboard.implementation ).to eq Clipboard::TestImplementation
+    end
+
+    it "warns when unknown implementation name is given" do
+      expect( $stderr ).to receive(:puts)
+      Clipboard.implementation = "unknown"
+      expect( Clipboard.implementation ).to eq Clipboard::File
+    end
   end
 end

data/spec/clipboard_windows_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+require "rbconfig"
+
+if RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
+  require 'clipboard/windows'
+
+  describe "Clipboard::Windows" do
+    before :all do
+      Clipboard.implementation = Clipboard::Windows
+    end
+
+    it "can copy & paste" do
+      Clipboard.copy('123windows')
+      expect( Clipboard.paste ).to eq '123windows'.encode("UTF-16LE")
+    end
+
+    it "can clear" do
+      Clipboard.copy('123windows')
+      expect( Clipboard.paste ).to eq '123windows'.encode("UTF-16LE")
+      Clipboard.clear
+      expect( Clipboard.paste ).to eq ''
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -2,4 +2,4 @@
 
 $LOAD_PATH.unshift 'lib'
 require 'clipboard'
-require 'clipboard/file'
+require 'clipboard/utils'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clipboard
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Jan Lelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-04 00:00:00.000000000 Z
+date: 2024-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '13.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '13.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -38,8 +38,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-description: 'Access to the clipboard on Linux, MacOS, Windows, and Cygwin: Clipboard.copy,
-  Clipboard.paste, Clipboard.clear'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: "Access the system clipboard \U0001F4CB︎ on Linux, MacOS, Windows, WSL,
+  Cygwin, GTK, or Java. Usage is as simple as calling Clipboard.copy or Clipboard.paste!"
 email:
 - hi@ruby.consulting
 executables: []
@@ -48,23 +62,33 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Gemfile
 - MIT-LICENSE.txt
 - README.md
+- Rakefile
 - clipboard.gemspec
 - lib/clipboard.rb
+- lib/clipboard/clipboard_load_error.rb
 - lib/clipboard/cygwin.rb
 - lib/clipboard/file.rb
 - lib/clipboard/gtk.rb
+- lib/clipboard/implementation.rb
 - lib/clipboard/java.rb
 - lib/clipboard/linux.rb
 - lib/clipboard/linux_wayland.rb
 - lib/clipboard/mac.rb
+- lib/clipboard/osc52.rb
 - lib/clipboard/utils.rb
 - lib/clipboard/version.rb
 - lib/clipboard/windows.rb
 - lib/clipboard/wsl.rb
 - spec/clipboard_file_spec.rb
+- spec/clipboard_java_spec.rb
+- spec/clipboard_linux_spec.rb
+- spec/clipboard_linux_wayland_spec.rb
+- spec/clipboard_mac_spec.rb
 - spec/clipboard_spec.rb
+- spec/clipboard_windows_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/janlelis/clipboard
 licenses:
@@ -79,17 +103,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- 'Linux: You need xclip / xsel (X11) or wl-clipboard (Wayland)'
-- 'Windows: You need the ffi gem'
+- 'Linux-X11: xclip or xsel'
+- 'Linux-Wayland: wl-clipboard'
+- 'Windows: ffi gem'
 rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
-summary: Access to the clipboard on Linux, MacOS, Windows, and Cygwin.
+summary: "Access the system clipboard \U0001F4CB︎ on Linux, MacOS, Windows, WSL, Cygwin,
+  GTK, or Java."
 test_files: []