| 1 |
GeniusPaste Plugin |
| 2 |
================== |
| 3 |
|
| 4 |
.. contents:: |
| 5 |
|
| 6 |
About |
| 7 |
----- |
| 8 |
This plugin allows the user to paste code from Geany into a configured |
| 9 |
pastebin service. At the moment it ships with builtin support these pastebin |
| 10 |
services, but more can be added: |
| 11 |
|
| 12 |
* codepad.org |
| 13 |
* dpaste.de |
| 14 |
* fpaste.org |
| 15 |
* pastebin.geany.org |
| 16 |
* paste.debian.net |
| 17 |
* sprunge.us |
| 18 |
|
| 19 |
GeniusPaste detects automatically the syntax of the code and pastes it |
| 20 |
with syntax highlighting enabled. |
| 21 |
It can also display the pasted code opening a new browser tab. |
| 22 |
|
| 23 |
Issues |
| 24 |
------ |
| 25 |
The API of the pastebin services can be updated at every moment. It |
| 26 |
may happen that GeniusPaste plugin could use an outdated API that meanwhile |
| 27 |
has been deprecated. |
| 28 |
|
| 29 |
If you get a unexpected API response during the paste process (practically |
| 30 |
if the plugin doesn't return a link to the pasted code), you will need to fix |
| 31 |
that pastebin service configuration to use its new API. If it is a |
| 32 |
configuration shipped with the plugin, please report the issue to: |
| 33 |
|
| 34 |
<enrico(dot)trt(at)gmail(dot)com> |
| 35 |
|
| 36 |
Requirements |
| 37 |
------------ |
| 38 |
* GTK+ >= 3.16 |
| 39 |
* libsoup 3.0 |
| 40 |
|
| 41 |
Installation |
| 42 |
------------ |
| 43 |
This plugin is part of the geany-plugins project. |
| 44 |
See the README file of that package. |
| 45 |
|
| 46 |
Pastebin configuration |
| 47 |
---------------------- |
| 48 |
|
| 49 |
Configuration for the pastebin services is looked up in one of data directories |
| 50 |
as follows, in order: ``$GEANY_CONFIG_DIR/plugins/geniuspaste/pastebins/`` and |
| 51 |
``$PREFIX/share/geany-plugins/geniuspaste/pastebins/`` (where |
| 52 |
``$GEANY_CONFIG_DIR`` is ``$HOME/.config/geany`` on \*NIX; and ``$PREFIX`` is |
| 53 |
generally either ``/usr/`` or ``/usr/local/`` under \*NIX). |
| 54 |
|
| 55 |
If more than one configuration file declare a pastebin service of the same |
| 56 |
name, only the first one found is used. This way, one can easily override the |
| 57 |
configuration in a system directory with a custom one in a user directory. |
| 58 |
|
| 59 |
Format |
| 60 |
^^^^^^ |
| 61 |
|
| 62 |
The pastebin configuration format uses an INI-style syntax. |
| 63 |
|
| 64 |
Placeholders |
| 65 |
++++++++++++ |
| 66 |
|
| 67 |
Values from the `[format] section`_ and the *replace* key in the `[parse] |
| 68 |
section`_ can contain references to placeholders with the syntax ``%name%`` |
| 69 |
(e.g. ``%contents%``). |
| 70 |
Custom placeholders can be defined in the `[defaults] section`_. |
| 71 |
|
| 72 |
The builtin placeholders are: |
| 73 |
|
| 74 |
*contents* |
| 75 |
The data to actually paste. |
| 76 |
*language* |
| 77 |
The language of the current document, as mapped through the `[languages] |
| 78 |
section`_. |
| 79 |
*title* |
| 80 |
The base name of the current document. |
| 81 |
*user* |
| 82 |
The configured author name. |
| 83 |
|
| 84 |
*[pastebin]* section |
| 85 |
++++++++++++++++++++ |
| 86 |
|
| 87 |
The *pastebin* section is required, and must contain at least the *name* and |
| 88 |
*url* keys. |
| 89 |
|
| 90 |
*name* |
| 91 |
The name of the pastebin service, as displayed to the user. This key is |
| 92 |
required. |
| 93 |
*url* |
| 94 |
The URL to which submit the data. This key is required. |
| 95 |
*method* |
| 96 |
The HTTP method to use to submit the data. Defaults to ``POST``. |
| 97 |
*content-type* |
| 98 |
The Content-Type the request body should be sent in. Currently supported |
| 99 |
types include ``application/x-www-form-urlencoded`` and ``application/json``. |
| 100 |
Defaults to ``application/x-www-form-urlencoded``. |
| 101 |
|
| 102 |
*[format]* section |
| 103 |
++++++++++++++++++ |
| 104 |
|
| 105 |
The *format* section describes the fields of the form to send to the pastebin. |
| 106 |
Each key in this section is a field, and each value that field's value. |
| 107 |
|
| 108 |
*[parse]* section |
| 109 |
+++++++++++++++++ |
| 110 |
|
| 111 |
If the *parse* section is declared, it defines the regular expression used to |
| 112 |
parse the raw response body from the pastebin service and build the final |
| 113 |
paste URL. |
| 114 |
|
| 115 |
If this section doesn't exist, the URI of the response itself is used, after |
| 116 |
any possible redirection. This is usually good for non-API pastebin services, |
| 117 |
where the server redirects the user to the paste page. |
| 118 |
|
| 119 |
**Warning:** If the *parse* section exists, it will be used, no matter whether |
| 120 |
any key is actually defined. This means that a ``[parse]`` line is enough to |
| 121 |
enable response body parsing, and it will use the default *search* and |
| 122 |
*replace* settings. |
| 123 |
|
| 124 |
*search* |
| 125 |
A regular expression (PCRE) pattern to match against the pastebin |
| 126 |
service's raw response data. |
| 127 |
Defaults to ``^[[:space:]]*(.+?)[[:space:]]*$``, i.e. capture everything |
| 128 |
but the leading and trailing whitespaces. |
| 129 |
*replace* |
| 130 |
The final URL, with regular expression capture groups from *search* |
| 131 |
expanded. Group references use the numeric, one-digit syntax: ``\0`` |
| 132 |
refers to the whole matched text, ``\1`` to the first captured group, and |
| 133 |
so on. Defaults to ``\1``, which works nicely with the default *search* |
| 134 |
pattern. |
| 135 |
|
| 136 |
*[defaults]* section |
| 137 |
++++++++++++++++++++ |
| 138 |
|
| 139 |
The *defaults* section defines default values for some builtin `placeholders`_ |
| 140 |
or define new placeholders. |
| 141 |
|
| 142 |
*[languages]* section |
| 143 |
+++++++++++++++++++++ |
| 144 |
|
| 145 |
The *languages* section maps Geany's filetype names (the keys) to the pastebin |
| 146 |
service's own name for this language. This allows to translate the filetypes |
| 147 |
Geany knows about to ones the pastebin service understands. |
| 148 |
|
| 149 |
|
| 150 |
License |
| 151 |
------- |
| 152 |
GeniusPaste is distributed under the terms of the GNU General Public |
| 153 |
License as published by the Free Software Foundation; either version 2 |
| 154 |
of the License, or (at your option) any later version. A copy of this |
| 155 |
license can be found in the file COPYING included with the source code |
| 156 |
of this program. If not, you will be able to get a copy by contacting |
| 157 |
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
| 158 |
Boston, MA 02110-1301, USA. |