Clip - Utility to copy image from clipboard to file.

Clip

Overview

Clip is a self-contained command line utility written in Scala to extract images from clipboard and save it to a file. It is a module of org-wiki project.

Motivation

This utility is useful to paste images on Emacs org-mode and markdown formats like github markdown.

Features

• Command line app. Can be integrated to Emacs or any other editor that supports run subprocesses.
• Cross-platform as any Java-app. Tested in Linux and Windows.
• Add pictures to org-mode or any markdown on the fly.

Design decisions

Scala was used in this application because Java platform has the more reliable API to access the clipboard in many platforms including Linux and Windows and the user doesn’t need to install any other dependency than Java.

If it was Python the user would have to install gtk or any GUI toolkit dependencies and binaries and also a Python distribution and would be hard distribute it as a self-contained one-file solution.

Usage

1. Save an image from clipboard to a file with given name.
   • $ java -jar Clip.jar --name imageName

It save the image in the clipboard to ./imagerName.png

Example:

$ java -jar ./target/scala-2.11/Clip-assembly-1.0.jar --name /tmp/image.png
file:/tmp/image.png

1. Save an image from clipboard to a file with a given name
   • $ java -jar Clip.jar --name imageName /tmp/directory

It saves the image in the clipboard to /tmp/directory/imageName.png

1. Copy an image from clipboard to file with an uuid (automatically generated name).
   • $ java -jar Clip.jar -uuid /tmp

It saves the image in the clipboard to file /tmp/715dbacb-c6d1-40db-8d91-c90e7217ace8.png

Example:

$ java -jar ./target/scala-2.11/Clip-assembly-1.0.jar --uuid /tmp 
tmp/715dbacb-c6d1-40db-8d91-c90e7217ace8.png

• 4. Print help and example:

$ java -jar ~/bin/Clip.jar 
Usage:

  Save clipboard image with a given Name

    $ javar -jar Clip.jar --name imageName
      -> save image to ./imageName.png and print ./imageName.png

    $ java -jar Clip.jar --name imageName  /tmp
      -> save image to /tmp/imageName.png and print /tmp/imageName.png

  Save clipboard image with an automatic generated name
    - UUID - Universal Unique Identifier

    $ java -jar Clip.jar --uuid /tmp
      -> save image to /tmp/415dafcf-5fd0-4d10-97f2-0da82bf1bf3f.png and print
         - 415dafcf-5fd0-4d10-97f2-0da82bf1bf3f.png

Build

Development Dependencies

To build it is necessary Scala and Sbt be installed on the system.

It is necessary Java >= v8.0 and Scala runtime >= v2.11.8

$ java -version
java version "1.8.0_74"
Java(TM) SE Runtime Environment (build 1.8.0_74-b02)
Java HotSpot(TM) 64-Bit Server VM (build 25.74-b02, mixed mode)

$ scala -version
Scala code runner version 2.11.8 -- Copyright 2002-2016, LAMP/EPFL

The Scala runtime can be downloaded from:

• Scala Download: https://www.scala-lang.org/download/

The Sbt building automation tool that is necessary to build and bundle the application with Scala run-time can be downloaded from:

• Sbt Download: http://www.scala-sbt.org/download.html
• Sbt Manual Installation: sbt Reference Manual — Installing sbt manually

Sbt can be installed with those commands:

mkdir -p ~/bin

# Download sbt building tool to  ~/bin/sbt-launch.ja
curl -L -o ~/bin/sbt-launch.jar https://repo.typesafe.com/typesafe/ivy-releases/org.scala-sbt/sbt-launch/0.13.13/sbt-launch.jar

# Create the sbt launch ~/bin/sbt 
cat  <<EOF > ~/bin/sbt
#!/bin/bash
SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M"
java \$SBT_OPTS -jar ~/bin/sbt-launch.jar "\$@"
EOF

# Make the sbt launcher executable 
chmod u+x ~/bin/sbt

# Optional: It is not necessary if ~/bin is already in the $PATH variable.
# Add ~/bin to $PATH variable permanently. Oor invoke it with absolute path ~/bin/sbt
#
echo "export PATH=\$PATH:~/bin" >> ~/.bashrc

Build instruction

1. Install Scala
2. Install Sbt
3. Run $ make to build the ubber jar. The output file will be ./target/scala-2.11/Clip-assembly-1.0.jar

If Make is not available the compilation can be run with $ sbt assembly.

Test

• $ make test1

Copy an image and enter $ make test1. If the app works it will write the image to the file clipboard.png.

• $ make test2

Copy an image to

The output will be like:

$ make test2
java -jar ./target/scala-2.11/Clip-assembly-1.0.jar -uuid . 
file:./fba53c12-3f23-4728-9f52-a26a3d285d7c.png

Emacs Client Code

Client code 1

This emacs command can be used to paste images. The command M-x org-paste-image ask the user the directory him whichs to paste and then it inserts the path to the image relative to current directory. If the current directory is ~ (/home/dummy) and the the current file is ~/test.org , if the user chooses to paste the file at directory ~/Pictures it inserts the path to the image file like this.

• file:Pictures/acb19f19-31c0-4550-874d-1111aafbb93f.png

The advantage of automatic name with UUID is that is easier to paste and move images without any name conflict or overwrite any image.

Warn: This code is synchrnous, therefor Emacs will be frozen while the process doesn’t finish. If it takes too long you can abort the execution with C-g.

(defvar clipjar-location "~/bin/Clip.jar")

(defun org-paste-image ()
     (interactive)
     (let* ((dir (read-directory-name "Dir: ")))       
       (insert        
        (org-make-link-string
         (concat "file:"
                 (shell-command-to-string
                  (mapconcat #'identity
                             `("java"
                               "-jar"
                               ,(expand-file-name clipjar-location)
                               "--uuid"
                               ,(file-relative-name dir default-directory)
                               )
                             " "
                             ))))))) 

The image can be identified with a caption attribute:

#+CAPTION: Power Supply Circuit Diagram.
file:Pictures/acb19f19-31c0-4550-874d-1111aafbb93f.png

Client code 2

(defvar clipjar-location "~/bin/Clip.jar")

(defun org-paste-image2 ()
     (interactive)
     (let* ((image-name (string-trim (read-string "Image name: "))))       
       (insert        
        (org-make-link-string
         (concat "file:"
                 (shell-command-to-string
                  (mapconcat #'identity
                             `("java"
                               "-jar"
                               ,(expand-file-name clipjar-location)
                               "--name"
                               ,(concat "'" image-name "'")        ;; image name without extension must be quoted
                               "'/tmp/scala images'"               ;; Directory which the image will be saved '/tmp/images scala'
                               )
                             " "
                             ))))))) 

Download Release

You can download a compilead binary release from:

• https://github.com/caiorss/clip.jar/blob/build/Clip.jar

The file is about 5 MB because it was compiled with the Scala run-time bundled with the app.

Or automatically with this bash script:

mkdir -p ~/bin &&  cd ~/bin && curl -O -L https://github.com/caiorss/clip.jar/raw/build/Clip.jar