====================
Case transformations
====================

Among the operations that can be performed on a string such as a file name are
case transformations such as making all alphabetic characters upper or lower
case or applying some style of mixed case. The ``tl.rename.case`` module
provides a number of functions that implement such transformations, as well as
one compound transformation that selects the implementation to apply by
interpreting the ``case`` option.

All these transformation functions take, as usual, an iterable of old file
names as an argument and return a list of transformed names. File names are
encoded strings; case transformations of byte values beyond 7 bits depend on
the locale, which is why we don't demonstrate them here as we cannot be sure
about the availability of any particular interesting locale.


Transforming to upper and lower case
====================================

These transformations simply apply the ``upper`` and ``lower`` methods of
Python's built-in strings.

>>> from tl.rename.case import transform_uppercase
>>> transform_uppercase(['foo/abc123.txt', 'Bar\xd7', 'BAZ -.*'])
['FOO/ABC123.TXT', 'BAR\xd7', 'BAZ -.*']

>>> from tl.rename.case import transform_lowercase
>>> transform_lowercase(['FOO/ABC123.TXT', 'Bar\xd7', 'baz -.*'])
['foo/abc123.txt', 'bar\xd7', 'baz -.*']


Sentence case
=============

Sentence case is a style of mixed case that applies upper case to the
beginning of the first word of a sentence as well as some exceptions such as
roman numerals:

>>> from tl.rename.case import transform_sentence_case
>>> transform_sentence_case(
...     ['foo bar baz', 'FOO 1 bar +-. Baz', 'foo  i bar\tMcDXx.txt'])
['Foo bar baz', 'Foo 1 bar +-. baz', 'Foo  I bar\tMCDXX.txt']

Sentence case is applied to each path segment:

>>> transform_sentence_case(['foo bar/baz asdf', '/foo/bar/baz asdf'])
['Foo bar/Baz asdf', '/Foo/Bar/Baz asdf']

Words that follow an ellipsis aren't capitalized even if they start a
sentence; whitespace around ellipses doesn't matter but there must be no
characters between the dots of an ellipsis:

>>> transform_sentence_case(['... foo', 'foo ... bar', '..123.. foo'])
['... foo', 'Foo ... bar', '..123.. Foo']


Selecting a case transformation by options
==========================================

The ``tl.rename.case`` module provides one transformation function that
selects and run a concrete case transformation by the value of the ``case``
option:

>>> from tl.rename.case import transform
>>> transform(['foo Bar'], case='upper')
['FOO BAR']
>>> transform(['foo Bar'], case='lower')
['foo bar']
>>> transform(['foo Bar'], case='sentence')
['Foo bar']

Non-existent case transformation identifiers will be ignored, as will the
absence of the option:

>>> transform(['foo Bar'], case='non-existent')
['foo Bar']
>>> transform(['foo Bar'])
['foo Bar']


.. Local Variables:
.. mode: rst
.. End:
