1# -*- coding: utf-8 -*-
2"""
3    pygments.formatter
4    ~~~~~~~~~~~~~~~~~~
5
6    Base formatter class.
7
8    :copyright: Copyright 2006-2020 by the Pygments team, see AUTHORS.
9    :license: BSD, see LICENSE for details.
10"""
11
12import codecs
13
14from pygments.util import get_bool_opt
15from pygments.styles import get_style_by_name
16
17__all__ = ['Formatter']
18
19
20def _lookup_style(style):
21    if isinstance(style, str):
22        return get_style_by_name(style)
23    return style
24
25
26class Formatter:
27    """
28    Converts a token stream to text.
29
30    Options accepted:
31
32    ``style``
33        The style to use, can be a string or a Style subclass
34        (default: "default"). Not used by e.g. the
35        TerminalFormatter.
36    ``full``
37        Tells the formatter to output a "full" document, i.e.
38        a complete self-contained document. This doesn't have
39        any effect for some formatters (default: false).
40    ``title``
41        If ``full`` is true, the title that should be used to
42        caption the document (default: '').
43    ``encoding``
44        If given, must be an encoding name. This will be used to
45        convert the Unicode token strings to byte strings in the
46        output. If it is "" or None, Unicode strings will be written
47        to the output file, which most file-like objects do not
48        support (default: None).
49    ``outencoding``
50        Overrides ``encoding`` if given.
51    """
52
53    #: Name of the formatter
54    name = None
55
56    #: Shortcuts for the formatter
57    aliases = []
58
59    #: fn match rules
60    filenames = []
61
62    #: If True, this formatter outputs Unicode strings when no encoding
63    #: option is given.
64    unicodeoutput = True
65
66    def __init__(self, **options):
67        self.style = _lookup_style(options.get('style', 'default'))
68        self.full = get_bool_opt(options, 'full', False)
69        self.title = options.get('title', '')
70        self.encoding = options.get('encoding', None) or None
71        if self.encoding in ('guess', 'chardet'):
72            # can happen for e.g. pygmentize -O encoding=guess
73            self.encoding = 'utf-8'
74        self.encoding = options.get('outencoding') or self.encoding
75        self.options = options
76
77    def get_style_defs(self, arg=''):
78        """
79        Return the style definitions for the current style as a string.
80
81        ``arg`` is an additional argument whose meaning depends on the
82        formatter used. Note that ``arg`` can also be a list or tuple
83        for some formatters like the html formatter.
84        """
85        return ''
86
87    def format(self, tokensource, outfile):
88        """
89        Format ``tokensource``, an iterable of ``(tokentype, tokenstring)``
90        tuples and write it into ``outfile``.
91        """
92        if self.encoding:
93            # wrap the outfile in a StreamWriter
94            outfile = codecs.lookup(self.encoding)[3](outfile)
95        return self.format_unencoded(tokensource, outfile)
96