1
The Newsbeuter Hacker's Guide
2
=============================
3
Andreas Krennmair <ak@synflood.at>
7
This is the "hacker's guide" to newsbeuter. It describes the overall architecture
8
of newsbeuter, the most important design decisions and some other noteworthy things
9
that don't belong anywhere else.
11
This guide assumes that you know about Unix programming with C++,
12
multithreading, and some more stuff. This is not for end users, so if you don't
13
have C++ programming experience, then this is not for you.
20
This section describes the different classes and their purpose.
22
*class cache*: the persistence backend of newsbeuter. It takes rss_item and
23
rss_feed objects and writes them to the cache.db using the SQLite library,
24
respectively reads the content of cache.db and creates rss_item and rss_feed
27
*class colormanager*: manages the color configuration. It hooks into the
28
configuration parser, stores the color configuration information and sets
29
them in the view. This is currently a bit ugly, because colormanager knows about
30
the internals of view resp. pb_view. This should be changed in a way that
31
colormanager knows nothing about who gets the configuration, and that the views
32
retrieve this configuration from colormanager. It is derived from
33
config_action_handler, a helper class for the configuration parser.
35
*class configcontainer*: manages the normal program configuration. It hooks into
36
the configuration parser and the stores the configuration information. Other
37
components can then query the configcontainer for configuration values. It is
38
derived from config_action_handler.
40
*class configparser*: parses the configuration file and hands over the results
41
to all hooked config_action_handler objects.
43
*class controller*: the controller does a lot of the work within newsbeuter. It
44
is the connector between view and cache. It parses the command line option,
45
controls the configuration parser and hands over data to the view. It also
46
contains code to control the reloading of feeds.
48
*class downloadthread*: a thread that does nothing but start a reload operation
49
for all feeds. Derived from thread.
51
*class htmlrenderer*: takes a string and renders the HTML it contains into a
52
textual representation. It also extracts URLs from a and img tag for later use.
54
*class keymap*: hooks into the configuration parser and manages all the
55
keymapping. Additionally, it generates the keymapping information with hint
58
*class logger*: helper class that manages the optional logging to a text file.
59
Logging can be enabled by developers (see below).
61
*class mutex*: a C++ wrapper around the pthread mutex.
63
*class reloadhtread*: similar to downloadthread, but starts a reload every n
64
minutes (configurable).
66
*class rss_feed*: represents an RSS feed, including RSS url, page link, title,
67
author, description and RSS items (articles). Uses the cache to persist itself.
68
Internally, all text data (especially the title and the author) are stored as
69
UTF-8 strings, but the getters return data that matches the current locale
72
*class rss_item*: represents an RSS item (article), including link to the
73
article, title, author, publication date and description. Internally, all text
74
data (especially the title, the author and the description) are stored as UTF-8
75
strings, but the getters return data that matches the current locale charset
78
*class stflpp*: a C++ wrapper around STFL. STFL is the ncurses widget library
79
that newsbeuter heavily relies upon.
81
*class thread*: a wrapper around Unix pthreads.
83
*class urlreader*: manages reading and writing the urls file, including handling
86
*class utils*: contains several static utility functions, such as a tokenizer,
87
the lock file code and a text converter that builds upon iconv.
89
*class view*: the class that draws the user interface. It also reads the user's
90
input and runs the accordings actions.
92
*class xmlpullparser*: although called xmlpullparser, it parses virtually
93
everything that vaguely looks like XML/HTML tags, even when totally invalid, and
94
provides the parsing result as a continuous stream of tokens (tags and text). It
95
is solely used by the htmlrenderer class.
99
TODO: describe interaction between classes.
105
Use text file as configuration
106
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107
The "classical" text tools, like vim, slrn and mutt, are all configurable
108
solely via text files. Newsbeuter follows the same spirit, especially since the
109
other prominent RSS feed readers for the text console primarily encourage
110
configuration via an often crude user interface within the application itself.
111
The consequence for newsbeuter is: no configuration via the user interface, but
112
solely via configuration files. Text editors are easier to handle than some
113
crude menus that are somehow hard to use.
115
Keep a good balance of customizability
116
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
The problem with user wishes is that too many people demand a possibility to
118
customize this bell or that whistle within newsbeuter. Often, these
119
possibilities only have a very limited purpose, and their value is in no
120
relation to the added complexity of the code. Every customization needs to be
121
tested, and means a lot more testing whenever some related code changes.
123
The code shouldn't get too bloated, it should be kept straight-forward and easy
124
to read. With too much customizability, this goal would be in danger.
126
Why C++ and not C, [insert your favorite language], ...?
127
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128
C++ has many advantages compared to other programming languages.
130
- C++ is backwards-compatible to C. That means we can theoretically use all the C libraries.
131
- C++ makes it easier to structure your program in an object-oriented way, and helps maintain inheritance hierarchies without a lot of fuzz.
132
- C++ compiles to fast, native code.
133
- C++ comes with an extensive standard library (see next section).
135
- C++ on Linux/Unix systems does not require any exotic compilers to be installed in order to compile newsbeuter. g++ (part of GCC) is enough.
137
These were the reasons why C++ was initially chosen, and it proved to be a useable language during the development process.
140
Use the full potential of modern C++
141
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143
The C++ standard library comes with an extensive set of algorithms and data
144
structures. Developers are encouraged to use especially the data structures,
145
because the available container classes are standardized, their behaviour and
146
usage is well-documented, and makes it possible to keeep the the overall logic
147
is a pretty high level. More complex things that can only be done in C (like
148
special system calls) /should/ be encapsulated by a wrapper class in order to
149
avoid potential mis-use of low-level functions and data structures. Good
150
examples for wrapping low-level stuff are *class rss_feed*, *class rss_item*
156
Getting a detailed debug log
157
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
158
If you want to get a detailed debug log from newsbeuter, you only need to run
159
newsbeuter with special parameters:
161
newsbeuter -d log.txt -l 5
163
Some of this output doesn't make sense very much unless you know the source
164
code, so it's only helpful for developers.
added
removed
doc/hackers-guide.txt
