:program:`lodgeit`
==================

.. program:: lodgeit

Usage
-----

:program:`lodgeit` retrieves and creates pastes.  The general syntax is::

   lodgeit [global options] action [options] [arguments]


Choosing a pastebin
^^^^^^^^^^^^^^^^^^^

:program:`lodgeit` supports different pastebins.  The pastebin can be chosen
with the :option:`lodgeit --pastebin`:

.. cmdoption:: --pastebin [HOSTNAME OR URL]

   Chose the pastebin to use.  It can either be a hostname of one of the
   builtin pastebins or a URL to the start page of a pastebin site based on
   the Lodgeit_ software.  The following pastebins are builtin:

   - ``paste.pocoo.org``:  http://paste.pocoo.org
   - ``bpaste.net``: http://bpaste.net

   The default pastebin can be configured with the :confkey:`pastebin`
   configuration key.


Create pastes
^^^^^^^^^^^^^

.. program:: lodgeit new

The ``new`` action creates a new paste paste from the given ``filename``.
If no ``filename`` is given, or if a single dash ``-`` is specified, the
paste is read from standard input.  A ``parent`` paste [1]_ may be specified as
id or url.  If ``parent`` is not given, the new paste has no parent::

   lodgeit new [options] [filename] [parent]

The following options are available:

.. cmdoption:: -c, --copy

   Copy the url of the created paste to the clipboard.  Enabled by default,
   can be configured with the configuration key :confkey:`copy`.

.. cmdoption:: -nc, --no-copy

   Do not copy the url of the created paste to the clipboard.

.. cmdoption:: -b, --browser

   Open the created paste in the favourite web browser.  On Unix-Systems you
   should set ``$BROWSER`` to something reasonable.  The default can be
   configured with the configuration key :confkey:`browser`.

.. cmdoption:: -nb, --no-browser

   Do not open the paste in the browser.

.. cmdoption:: -p, --private

   Create a private paste.  Private pastes do not have a nummeric id and do
   not appear in the public list of all pastes.  The default can be
   configured with the configuration key :confkey:`private`.

.. cmdoption:: -np, --no-private

   Create a public paste.

.. cmdoption:: -l LANGUAGE, --language LANGUAGE

   Force ``LANGUAGE`` as markup language.  If unset, the language is guess
   from the filename (doesn't work for standard input, of course).  A
   default language can be set with the configuration key
   :confkey:`language`.  Use ``lodgeit list_languages`` to get a list of
   available languages.

.. cmdoption:: --encoding ENCODING

   The encoding of the input file.  If unset, the system encoding is used.
   A default encoding can be set with the configuration key
   :confkey:`encoding`.


Retrieve pastes
^^^^^^^^^^^^^^^

.. program:: lodgeit get

The ``get`` action fetches the given ``paste``.  ``paste`` can be a paste id
or a complete paste url.  If no paste is given, the last public paste is
fetched::

   lodgeit get [options] [paste]

The following options are available:

.. cmdoption:: -o OUTFILE, --outfile OUTFILE

   Write the paste to the specified file.  If ``OUTFILE`` is single dash
   ``-`` or if this option is not given, the paste is written to standard
   output.

.. cmdoption:: -p, --parent

   Fetch the parent of the specified paste [1]_.

.. cmdoption::  -i, --information

   Write a header with meta data before the paste.  This header
   contains the following information:

   - the paste id
   - the date and time of publication
   - the programming or markup language
   - the id of the parent paste
   - the url of the paste

   The default can be configured with configured with the configuration key
   :confkey:`information`.

.. cmdoption:: -ni, --no-information

   Do not write the meta data header.

.. cmdoption::  -c, --color

   Use colored output.  This will highlight the paste according to the
   language of the paste.  If neither this option nor :option:`-nc` are
   given, output is colored, if the output file is a tty.  Can be configured
   with the configuration key :confkey:`color`.

.. cmdoption:: -nc, --no-color

   Do not use colored output.

.. cmdoption:: -s {light,dark}, --colorscheme {light,dark}

   The color scheme to use, if colored output is enabled.  Use ``light`` for
   terminals with a light background color and ``dark`` for terminals with a
   dark background color.  The default can be configured with the
   configuration key :confkey:`colorscheme`.


Configuration
-------------

.. highlight:: ini

Some options have configurable defaults, which can be adjusted with the
following configuration keys:

.. confkey:: pastebin

   The default pastebin.  See :option:`lodgeit --pastebin` for a description
   of this setting and permitted values.  The default is ``paste.pocoo.org``.

.. confkey:: language

   The default language for new pastes.  Corresponds to
   :option:`lodgeit new -l`.

.. confkey:: copy

   Boolean key providing the default setting for :option:`lodgeit new -c`
   and :option:`lodgeit new -nc`.  If ``true``, copying of paste urls is
   enabled, if ``false`` (the default), it's disabled.

.. confkey:: browser

   Boolean key providing the default setting for :option:`lodgeit new -b`
   and :option:`lodgeit new -nb`.  If ``true``, browsing of new pastes urls
   is enabled, if ``false`` (the default), it's disabled.

.. confkey:: private

   Boolean key providing the default setting for :option:`lodgeit new -p` and
   :option:`lodgeit new -np`.  If ``true``, new pastes are private by default,
   if ``false`` (the default), they are public.

.. confkey:: encoding

   Provides the default encoding for input files for :program:`lodgeit get`.
   Corresponds to :option:`lodgeit new --encoding`.

.. confkey:: information

   Boolean key providing the default setting for :option:`lodgeit get -i`
   and :option:`lodgeit get -ni`.  If ``true``, a header is written by
   default, if ``false`` (the default), the header is suppressed.

.. confkey:: color

   Boolean key providing the default setting for :option:`lodgeit get -c`
   and :option:`lodgeit get -nc`.  If ``true``, a output is colored by
   default, if ``false``, it's not.  If unset, colored output is only used
   on TTYs.

.. confkey:: colorscheme

   The default color scheme for colored output.  Corresponds to
   :option:`lodgeit get -s`, see the option description for permitted
   values.  The default is ``dark``.

Boolean configuration keys are true, if their value is any of ``true``,
``yes``, ``on`` and ``1`` (not case sensitive) and false, if their value is
any of ``false``, ``no``, ``off`` and ``0`` (again not case sensitive).
Other values cause an error.

The configuration file uses classic INI-style syntax.  Keys and values are
separated with ``=``, comments are started with ``#``::

   encoding = utf-8
   # open the browser
   browser = yes
   # do not copy url to clipboard
   copy = false

On POSIX systems, the configuration file is read from
:file:`$XDG_CONFIG_HOME/lodgeitrc`.  :envvar:`XDG_CONFIG_HOME` defaults to
`$HOME/.config`.  On Windows the configuration is read from
:file:`$APPDATA/lodgeitrc`.


Examples
--------

.. highlight:: text

Create a new paste::

   lodgeit new foo.py

Create a new private paste::

   lodgeit new -p foo.py

Open the new paste in the browser::

   lodgeit new -b foo.py

Fetch the last paste::

   lodgeit get

Show the information header::

   lodgeit get -i

Fetch a paste by id::

   lodgeit get C76X4sCbP3FEUCDBbFGa

Or by a complete url::

   lodgeit get 'http://paste.pocoo.org/show/C76X4sCbP3FEUCDBbFGa/'

Fetch and save a paste::

   lodgeit get -o hello.py C76X4sCbP3FEUCDBbFGa


.. rubric:: Footnotes

.. [1] See `Advanced Features`_ for a description of this feature.

.. _`Advanced Features`: http://paste.pocoo.org/help/advanced/
.. _`Lodgeit`: http://dev.pocoo.org/projects/lodgeit/