goldsborough/ecstasy

View on GitHub
README.rst

Summary

Maintainability
Test Coverage
*******
Ecstasy 
*******

.. image:: https://travis-ci.org/goldsborough/ecstasy.svg?branch=master
    :target: https://travis-ci.org/goldsborough/ecstasy

.. image:: https://img.shields.io/github/license/mashape/apistatus.svg
    :target: http://goldsborough.mit-license.org

.. image:: https://badge.fury.io/py/ecstasy.svg
    :target: http://badge.fury.io/py/ecstasy

.. image:: https://coveralls.io/repos/goldsborough/ecstasy/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/goldsborough/ecstasy?branch=master

.. image:: https://landscape.io/github/goldsborough/ecstasy/master/landscape.svg?style=flat
    :target: https://landscape.io/github/goldsborough/ecstasy/master

.. image:: https://codeclimate.com/github/goldsborough/ecstasy/badges/gpa.svg
    :target: https://codeclimate.com/github/goldsborough/ecstasy

.. image:: http://img.shields.io/gratipay/goldsborough.svg
    :target: https://gratipay.com/~goldsborough/

\

Ecstasy is here to make your command-line tool beautiful and fancy.

**Your command-line tool's output without ecstasy:**

.. image:: https://raw.githubusercontent.com/goldsborough/ecstasy/master/docs/img/without.png

\

**Your command-line tool's output with (on?) ecstasy:**

.. image:: https://raw.githubusercontent.com/goldsborough/ecstasy/master/docs/img/with.gif

Usage
=====

To use ecstasy, you mark up a standard Python string using ecstasy's special syntax, chose some sassy styling and formatting flags, pass them on to the package-level beautify() method and, in return, get your beautified string, ready to kick ass when printed to your command-line:

.. code-block:: python

    import ecstasy

    # <...> is a normal phrase, its style is determined by its position
    # <(x)...> is a phrase with an argument, its style is the one at index 'x'
    # <<...> <...>> is a phrase with nested phrases, their styles cascade
    text = "<Cats> are <(0)just> <<small>, furry <elephants>>!"

    # Beautify text by specifying styles via flag combinations
    text = ecstasy.beautify(text,
                ecstasy.Style.Blink   | ecstasy.Color.Red,
                ecstasy.Style.Bold    | ecstasy.Fill.Blue,
                ecstasy.Color.Magenta | ecstasy.Style.Underline,
                small=ecstasy.Style.Invert | ecstasy.Color.White)

    # Keyword arguments (small=...) cause all phrases matching the string of
    # the key to have the style specified by the keyword argument's value.

    print(text)

Running this in a script from a command-line outputs:

.. image:: https://raw.githubusercontent.com/goldsborough/ecstasy/master/docs/img/usage.gif

Installation
============

Now that you're convinced, you can install ecstasy with pip:

::

    $ pip install ecstasy

... and get crackin'.

`Documentation <http://ecstasy.readthedocs.org/en/latest/>`_
============================================================

Full documentation and usage descriptions specifying all possible options and possibilities of how you can beautify your strings with *ecstasy* can be found `here <http://ecstasy.readthedocs.org/en/latest/>`_.

Compatibility
=============

Python Versions
---------------

Built with Python 3.4 and Python 2.7. Additionally successfully backported to and tested with Python 2.6, 3.2 and also 3.3. See what `Travis <https://travis-ci.org/goldsborough/ecstasy>`_ has to say about it.

Terminal Support
----------------

Works out of the box with your Mac's terminal. For more information, please enjoy this table:

==========  ====  ===  ==========  =====  ======  ======  =====
Terminal    Bold  Dim  Underlined  Blink  Invert  Hidden  Color
==========  ====  ===  ==========  =====  ======  ======  =====
aTerm        ✓     X       ✓        X       ✓       X       ✓
Eterm       (\1)   X       ✓        X       ✓       X       ✓
GNOME        ✓     ✓       ✓        X       ✓       ✓       ✓
Guake        ✓     ✓       ✓        X       ✓       ✓       ✓
Konsole      ✓     X       ✓        ✓       ✓       X       ✓
Nautilus     ✓     ✓       ✓        X       ✓       ✓       ✓
rxvt         ✓     X       ✓       (\2)     ✓       X       ✓
Terminator   ✓     ✓       ✓        X       ✓       ✓       ✓
Tilda        ✓     X       ✓        X       ✓       X       ✓
XFCE4        ✓     ✓       ✓        X       ✓       ✓       ✓
XTerm        ✓     X       ✓        ✓       ✓       ✓       ✓
xvt          ✓     X       ✓        X       ✓       X       X
Linux TTY    ✓     X       X        X       ✓       X       ✓
VTE          ✓     ✓       ✓        X       ✓       ✓       ✓
==========  ====  ===  ==========  =====  ======  ======  =====

\

(\1) Lighter colors instead of bold.

(\2) Lighter colors instead of blink.

`License <http://goldsborough.mit-license.org>`_
================================================

Ecstasy is released under the `MIT license <http://goldsborough.mit-license.org>`_.

Authors
=======

Peter Goldsborough & `cat <https://goo.gl/IpUmJn>`_ :heart:


.. image:: https://badges.gitter.im/Join%20Chat.svg
   :alt: Join the chat at https://gitter.im/goldsborough/ecstasy
   :target: https://gitter.im/goldsborough/ecstasy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge