4 author: Michael Orlitzky
5 maintainer: Michael Orlitzky <michael@orlitzky.com>
8 license-file: doc/LICENSE
17 Parse XML files from The Sports Network feed.
22 htsn [OPTIONS] [HOSTNAMES]
25 The Sports Network <http://www.sportsnetwork.com/> offers an XML feed
26 containing various sports news and statistics. The goal of /htsn/
27 is to watch the XML feed and parse the individual XML documents into
30 Once started, we will choose an XML feed host to connect to. The
31 choice is made from a list in a round-robin fashion, and by default,
32 the list contains all known TSN feed hosts. Once we have a connection,
33 your username and password are sent. If they are accepted, we begin to
34 parse the feed saving all XML files to the configured output directory
35 (see @--output-directory@).
37 If we encounter an error (say, the connection is dropped), then we
38 will attempt to connect to the next host in the list after waiting
39 five seconds. This process continues indefinitely.
41 The program can run either interactively (that is, outputting to the
42 console), or as a daemon with the @--daemonize@ flag.
46 The program takes no input; a username and password must be supplied
47 on the command-line or in a configuration file.
51 Output is not generated when running as a daemon; otherwise, standard
52 out and standard error are fairly noisy. All traffic between /htsn/ and
53 the feed server is displayed on stdout. Status messages are
54 interspersed when they are generated with warnings and errors going to
55 stderr. The following can be expected:
57 * The only data we send to the feed are the username and password.
58 These will be highlighted in green on stdout.
60 * All data received from the feed will be echoed in the default color
63 * Informational messages will be highlighted in cyan and sent to stdout.
65 * Warnings will be highlighted in yellow and sent to stderr.
67 * Errors will be highlighted in red and sent to stderr.
71 Logging is done either to syslog or a file. The destination and
72 verbosity are controlled by the @--log-file@, @--log-level@,
73 and @--syslog@ parameters which may be specified either on the command
74 line or in the configuration file.
82 Run as a daemon, in the background. When running as a daemon the
83 \--pidfile, --run-as-group, and --run-as-user flags become relevant.
91 If you specify a file here, logs will be written to it (possibly in
92 addition to syslog). Can be either a relative or absolute path. It
93 will not be auto-rotated; use something like logrotate for that.
101 How verbose should the logs be? We log notifications at four levels:
102 DEBUG, INFO, WARN, and ERROR. Specify the \"most boring\" level of
103 notifications you would like to receive (in all-caps); more
104 interesting notifications will be logged as well. The debug output is
105 extremely verbose and will not be written to syslog even if you try.
110 \--output-directory, -o
113 To which directory should we write the XML files?
121 The password associated with your TSN username. A password is
122 required, so you must supply one either on the command line or in a
131 (Daemon mode only) Create a PID file in the given location. This is
132 used by the init system on Unix to keep track of the running daemon.
134 If necessary, its parent directory will be created with owner/group
135 set to the appropriate user/group, but at most one directory will
136 be created (that is, we won't create an entire directory tree).
138 Default: \/run\/htsn\/htsn.pid
144 (Daemon mode only) Run as the given system group. The PID file is
145 written before privileges are dropped, so the only privileges needed
146 by /htsn/ are those necessary to write the XML files and (optionally)
149 Default: the current group
155 (Daemon mode only) Run as the given system user. The PID file is
156 written before privileges are dropped, so the only privileges needed
157 by /htsn/ are those necessary to write the XML files and (optionally)
160 Default: the current user
166 Enable logging to syslog. On Windows this will attempt to communicate
167 (over UDP) with a syslog daemon on localhost, which will most likely
176 Your TSN username. A username is required, so you must supply one
177 either on the command line or in a configuration file.
183 It is possible to pass a list of feed hostnames on the command-line
184 (see [HOSTNAMES] in the synopsis). By default /htsn/ will attempt
185 to connect to every known TSN XML feed host in a round-robin fashion,
186 so there is rarely a need to do this.
188 /Configuration File/:
190 Any of the command-line options mentioned above can be specified in a
191 configuration file instead. We first look for \"htsnrc\" in the
192 system configuration directory. We then look for a file named
193 \".htsnrc\" in the user's home directory. The latter will override
196 The user's home directory is simply $HOME on Unix; on Windows it's
197 wherever %APPDATA% points. The system configuration directory
198 is determined by Cabal; the /sysconfdir/ parameter during
199 the \"configure\" step is used.
201 The file's syntax is given by examples in the htsnrc.example file
202 (included with /htsn/).
204 Options specified on the command-line override those in either
212 configurator == 0.2.*,
217 htsn-common == 0.0.1,
222 tasty-hunit == 0.4.*,
236 OptionalConfiguration
243 -fwarn-missing-signatures
244 -fwarn-name-shadowing
248 -fwarn-incomplete-record-updates
249 -fwarn-monomorphism-restriction
250 -fwarn-unused-do-bind
261 type: exitcode-stdio-1.0
262 hs-source-dirs: src test
263 main-is: TestSuite.hs
267 configurator == 0.2.*,
272 htsn-common == 0.0.1,
277 tasty-hunit == 0.4.*,
280 -- It's not entirely clear to me why I have to reproduce all of this.
284 -fwarn-missing-signatures
285 -fwarn-name-shadowing
289 -fwarn-incomplete-record-updates
290 -fwarn-monomorphism-restriction
291 -fwarn-unused-do-bind
295 -- These won't work without shelltestrunner installed in your
296 -- $PATH. Maybe there is some way to tell Cabal that.
297 test-suite shelltests
298 type: exitcode-stdio-1.0
299 hs-source-dirs: src test
300 main-is: ShellTests.hs
304 configurator == 0.2.*,
309 htsn-common == 0.0.1,
315 tasty-hunit == 0.4.*,
318 -- It's not entirely clear to me why I have to reproduce all of this.
322 -fwarn-missing-signatures
323 -fwarn-name-shadowing
327 -fwarn-incomplete-record-updates
328 -fwarn-monomorphism-restriction
329 -fwarn-unused-do-bind
333 source-repository head
335 location: http://michael.orlitzky.com/git/htsn.git