Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rexim/org-cliplink

Insert org-mode links from clipboard
https://github.com/rexim/org-cliplink

emacs-lisp hacktoberfest org-mode

Last synced: 2 months ago
JSON representation

Insert org-mode links from clipboard

Awesome Lists containing this project

README 

        
[[http://melpa.org/#/org-cliplink][file:http://melpa.org/packages/org-cliplink-badge.svg]]

[[https://travis-ci.org/rexim/org-cliplink][file:https://travis-ci.org/rexim/org-cliplink.svg?branch=master]]

[[https://coveralls.io/r/rexim/org-cliplink][file:https://coveralls.io/repos/rexim/org-cliplink/badge.svg]]



* org-cliplink



  [[http://i.imgur.com/oA0birm.gif]]



  A simple command that takes a URL from the clipboard and inserts an

  org-mode link with a title of a page found by the URL into the

  current buffer.



  This code was a part of my Emacs config almost a year. I decided to

  publish it as a separate package in case someone needs this feature

  too.



* Usage



** org-cliplink



   Bind ~org-cliplink~ function to something. For example, put this

   line in your init file:



   #+BEGIN_SRC emacs-lisp

     (global-set-key (kbd "C-x p i") 'org-cliplink)

   #+END_SRC



   Then copy any http/https URL to the clipboard, switch to the Emacs

   window and hit ~C-x p i~.



** org-cliplink-capture



   ~org-cliplink~ version for [[https://www.gnu.org/software/emacs/manual/html_node/org/Capture.html#Capture][org-capture]] templates. Makes synchronous

   request. Returns the link instead of inserting it to the current

   buffer. *Doesn’t support Basic Auth. Doesn’t support cURL

   transport.*



   Here is how it's supposed to be used in [[https://www.gnu.org/software/emacs/manual/html_node/org/Capture-templates.html#Capture-templates][org-capture-templates]]:



   #+BEGIN_SRC emacs-lisp

     (setq org-capture-templates

        '(("K" "Cliplink capture task" entry (file "")

           "* TODO %(org-cliplink-capture) \n  SCHEDULED: %t\n" :empty-lines 1)))

   #+END_SRC



** Custom Transformers



   You can actually customize how org-cliplink transforms and inserts

   url and title to the current buffer. To do that use

   ~org-cliplink-insert-transformed-title~ function. It takes the URL

   and a CALLBACK which is invoked when the title is retrieved.



   For example, if you want to strip off ~Github - :~

   from the GitHub titles you can implement the following

   ~custom-org-cliplink~ function and use it instead of the original

   ~org-cliplink~:



   #+BEGIN_SRC emacs-lisp

     (defun custom-org-cliplink ()

       (interactive)

       (org-cliplink-insert-transformed-title

        (org-cliplink-clipboard-content)     ;take the URL from the CLIPBOARD

        (lambda (url title)

          (let* ((parsed-url (url-generic-parse-url url)) ;parse the url

                 (clean-title

                  (cond

                   ;; if the host is github.com, cleanup the title

                   ((string= (url-host parsed-url) "github.com")

                    (replace-regexp-in-string "GitHub - .*: \\(.*\\)" "\\1" title))

                   ;; otherwise keep the original title

                   (t title))))

            ;; forward the title to the default org-cliplink transformer

            (org-cliplink-org-mode-link-transformer url clean-title)))))

   #+END_SRC



* Requirements



  - Linux

  - Emacs version 24.4+

  - cURL 7.35.0+ (optional)



** Windows



   Windows is not officially supported until [[https://github.com/rexim/org-cliplink/issues/35][#35]] is resolved.



   - GnuTLS — if you use Emacs installation from the official GNU FTP

     server — ftp://ftp.gnu.org/gnu/emacs/windows/ — you may simply

     download the latest version of GnuTLS from

     ftp://ftp.gnutls.org/gcrypt/gnutls/w32/ and copy the content of

     the downloaded archive to the emacs installation folder.



* Bugs



  https://github.com/rexim/org-cliplink/labels/bug



* Development



  1. open ~org-cliplink.el~ in Emacs;

  2. change something;

  3. ~M-x eval-buffer RET~;

  4. manual testing;

  5. go to 3 until it's done;



** Automated testing



   For automated testing you need to install [[http://cask.readthedocs.org/en/latest/][Cask]] first.



   To run unit tests:



   #+BEGIN_SRC bash

     $ cask # only once to download development dependencies

     $ cask exec ert-runner

   #+END_SRC



   To run integration and unit tests together:



   #+BEGIN_SRC bash

     $ ./run-travis-ci.sh

   #+END_SRC



   This exact script is run on every push to [[https://github.com/rexim/org-cliplink][org-cliplink GitHub repo]]

   on [[https://travis-ci.org/rexim/org-cliplink/][Travis CI]] (that's why it's called ~run-travis-ci.sh~). This

   script starts up a testing web-server, executes integrations tests

   defined in ~*-integration-tests.el~ files and executes unit tests

   after that.



   You can start the testing web-server standalone:



   #+BEGIN_SRC bash

     $ ./run-testing-server.py

   #+END_SRC



   It requires Python 2.7.6+. It will serve ~test-data/site~ folder on

   different ports with different features (like HTTPS, Gziped

   content, Basic Auth, etc.).



   To stop the server just ~^C~ it.



   The automated testing stuff was tested only under Linux so far.



** Contribution



   This command doesn't handle some cases (like different encodings) but

   I do my best to improve it. If you find this code useful and want to

   make a contribution I'm waiting for your pull requests. :)

   

   Thanks.