Metadata-Version: 1.0
Name: quoter
Version: 0.107
Summary: A simple way to quote text
Home-page: https://bitbucket.org/jeunice/quoter
Author: Jonathan Eunice
Author-email: jonathan.eunice@gmail.com
License: UNKNOWN
Description: In dealing with text, one quotes values all the time. Single quotes.
        Double quotes. Curly quotes. Backticks.
        Funny Unicode quotes. HTML or XML markup code.
        *Et cetera.*
        
        That process of wrapping values in surrounding text is almost always
        *ad hoc*, which can be tiresome and error-prone. This module
        provides an alternative: A clean,
        consistent way to quote values.
        
        Usage
        =====
        
        ::
        
            from quoter import single, double, backticks, braces
            
            print single('this')
            print double('that')
            print backticks('ls -l')
            print braces('curlycue')
            
        yields::
        
            'this'
            "that"
            `ls -l`
            {curlyqueue}
            
        A handful of the most common quoting styles is pre-defined:
        
         *  ``braces`` ``{example}``
         *  ``brackets`` ``[example]``
         *  ``angles`` ``<example>``
         *  ``parens`` ``(example)``
         *  ``double`` ``"example"``
         *  ``single`` ``'example'``
         *  ``backticks`` ``\`example\```
         *  ``anglequote`` ` 
         *   ``curlysingle``  
         *   ``curlysdouble``
        
        But there are a *huge* number of ways you might want to wrap
        or quote text. Even considering just "quotation marks," there are
        `well over a dozen <http://en.wikipedia.org/wiki/Quotation_mark_glyphs>`_.
        There are also `numerous bracketing symbols
        in common use <http://en.wikipedia.org/wiki/Bracket>`_. That's to say
        nothing of the constucts seen in markup, programming, and templating
        languages. Therefore
        ``quoter`` does not attempt to provide options for every possible quoting style.
        In addition to pre-defining some of the more common styles, it provides a
        general-purpose mechanism for defining your own::
        
            from quoter import Quoter
            
            bars = Quoter('|')
            print bars('x')
            
            plus = Quoter('+','')
            print plus('x')
            
            para = Quoter('<p>', '</p>')
            print para('this is a paragraph')
            
            variable = Quoter('${', '}')
            print variable('x')
            
        yields::
        
            |x|
            +x
            <p>this is a paragraph</p>
            ${x}
            
        Note that ``bars`` specifies just once quote symbol. If only one is given,
        the prefix and suffix are considered to be identical. If you really only want
        a prefix or a suffix, and not both, then define the ``Quoter`` with one of them
        as the empty string, as in ``plus`` above.
        
        Formatting and Encoding
        =======================
        
        The Devil, as they say, is in the details. We often don't just want quote
        marks wrapped around values. We also want those values set apart from
        the rest of the text. ``quoter`` supports this with ``padding`` and ``margin``
        settings patterned on the `CSS box model <http://www.w3.org/TR/CSS2/box.html>`_.
        In CSS, moving out from content one finds padding, a border, and then a margin.
        Padding can be thought of as an internal margin, and
        the prefix and suffix strings like the border. With that in mind::
        
            print braces('this')                      # '{this}'
            print braces('this', padding=1)           # '{ this }'
            print braces('this', margin=1)            # ' {this} '
            print braces('this', padding=1, margin=1) # ' { this } '
        
        If desired, the ``padding`` and ``margin`` can be given as
        strings, though usually they will be integers specifying the
        number of spaces surrounding the text.
        
        One can also define the ``encoding`` used for each call, per instance,
        or globally. If some of your quote
        symbox use Unicode characters, yet your output medium doesn't support
        them directly, this is an easy fix. E.g.::
        
            Quoter.encoding = 'utf-8'
            print curlydouble('something something')
        
        Will output UTF-8 bytes. But in general, this is just a convenience
        funciton. If you're using Unicode glyphs, you should manage
        encoding at the time of input and output, not as each
        piece of output is
        constructed.
        
        Dynamic Quoters
        ===============
        
        It is possible to define ``Quoters`` that don't just concatenate text, but
        that examine it and provide dynamic rewriting on the fly. For example,
        in finance, one often wants to present numbers with a special formatting::
        
            from quoter import LambdaQuoter
            
            f = lambda v: ('(', abs(v), ')') if v < 0 else ('', v, '')
            financial = LambdaQuoter(f)
            print financial(-3)
            print financial(45)
            
            password = LambdaQuoter(lambda v: ('', 'x' * len(v), ''))
            print password('secret!')
            
        yields::
        
            (3)
            45
            xxxxxxx
            
        The trick is giving the LambdaQuoter a ``lambda`` expression that
        accepts one value and returns a tuple of three values: the quote
        prefix, the value (possibly rewritten), and the suffix. 
            
        Alternate API
        =============
        
        It may be that you don't want a separate quote function for every
        style possible. In that case, registered styles can all be accessed
        through a single function::
        
            from quoter import quote
            
            print quote('tag', 'anglebrackets')
        
        yields::
        
            <tag>
            
        A style is 'registered' when it's created if it's given a name.
        For example, to register the template variable style above, we'd
        use::
        
            variable = Quoter('${', '}', name='variable')
            print quote('myvar', style='variable')
            
        Extended X/HTML Usage
        =====================
        
        There is an extended quoting mode designed for HTML construction.
        Instead of prefix and suffix strings, it takes tag names. Or
        more accurately, tag specifications. Like `jQuery <http://jquery.com>`_
        it supports ``id`` and ``class`` attributes in a style similar to
        that of CSS selectors. It also understands that some
        elements are 'void', meaning they do not want or need
        closing tags.::
        
            from quoter import HTMLQuoter
            
            para = HTMLQuoter('p')
            print para('this is great!', {'class':'emphatic'})
            print para('this is great!', '.emphatic')
            
            para_e = HTMLQuoter('p.emphatic')
            print parae('this is great!')
            print parae('this is great?', '.question')
            
            br = HTMLQuoter('br', void=True)
            print br()
        
        ``HTMLQuoter`` basically works, but buyer beware: It's
        not as well tested as the rest of the
        module.
        
        Installation
        ============
        
        ::
        
            pip install quoter
            
        (You may need to prefix this with "sudo " to authorize installation.)
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
