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 [[https://github.com/caiorss/org-wiki][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
Save an image from clipboard to a file with given name.
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
Save an image from clipboard to a file with a given name
It saves the image in the clipboard to /tmp/directory/imageName.png
Copy an image from clipboard to file with an uuid (automatically generated name).
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
$ 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.pngSave 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
** 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:
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: [[http://www.scala-sbt.org/0.13/docs/Manual-Installation.html][sbt Reference Manual — Installing sbt manually]]
Sbt can be installed with those commands:
mkdir -p ~/bin
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
cat <
SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M" java \$SBT_OPTS -jar ~/bin/sbt-launch.jar "\$@" EOF
chmod u+x ~/bin/sbt
# echo "export PATH=\$PATH:~/bin" >> ~/.bashrc
Build instruction
Install Scala
Install Sbt
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
Copy an image and enter $ make test1. If the app works it will write the image to the file clipboard.png.
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.
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:
file:Pictures/acb19f19-31c0-4550-874d-1111aafbb93f.png
[[file:images/example-org-paste-image-uuid.gif]]
*** 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'
)
" "
)))))))
[[file:images/example-org-paste-image2.gif]]
** Download Release
You can download a compilead binary release from:
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