News configuration

The following configuration items define how Liberator manages news headline data.

Contents:

add-newscodes

add-newscodes specifies a list of strings that Liberator should identify as news codes regardless of whether the strings meet the criteria for automatic identification of news codes. Special characters used in news codes listed in add-newscodes do not need to be listed in newscode-valid-charsadd-newscodes only takes effect if newscode-exceptions is TRUE.

Liberator does not support lower-case letters in news codes. Using add-newscodes and/or newscode-valid-chars to make Liberator recognise news codes containing lower-case letters will not have the intended effect. Liberator converts all news codes to upper-case before they are matched against a search string.

add-newscodes is one of the items used by Liberator to determine if a filter string applied to a news feed is a news code or a general search string. A news feed's filter string is automatically identified as a news code if either of the following two criteria are met:

Syntaxadd-newscodes <newscode1> <newscode2> ... <newscodeN>

Type: array of strings (space separated)

Default value: none

newscode-exceptions

newscode-exceptions specifies whether to allow specific exceptions to the rules for identifying news codes.

newscode-exceptions is one of the items used by Liberator to determine if a filter string applied to a news feed is a news code or a general search string. A news feed's filter string is automatically identified as a news code if either of the following two criteria are met:

Syntaxnewscodes-exceptions TRUE

Type: boolean

Default value: FALSE (no exceptions to the rules for identifying newscodes are allowed)

newscode-max-length

newscode-max-length sets the maximum length of a filter string that can be automatically identified as a news code.

newscode-max-length is one of the items used by Liberator to determine if a filter string applied to a news feed is a news code or a general search string. A news feed's filter string is automatically identified as a news code if either of the following two criteria are met:

Syntaxnewscode-max-length <max-filter-string-length>

Type: integer

Default value: 4

newscode-valid-chars

newscode-valid-chars controls the range of punctuation characters that may be present in a valid news code. Upper-case letters are recognised as valid characters by default and don't need to be specified in newscode-valid-chars.

Liberator does not support lower-case letters in news codes. Using add-newscodes and/or newscode-valid-chars to make Liberator recognise news codes containing lower-case letters will not have the intended effect. Liberator converts all news codes to upper-case before they are matched against a search string.

newscode-valid-chars is one of the items used by Liberator to determine if a filter string applied to a news feed is a news code or a general search string. A news feed's filter string is automatically identified as a news code if either of the following two criteria are met:

Syntaxnewscode-valid-chars <valid-characters>

Type: string

Default value: "/."

newsitems-max

newsitems-max specifies the maximum number of news headlines that Liberator sends to a client for any one request.

Syntaxnewsitems-max <number-of-headlines>

Type: integer

Default value: 500

newsitems-saved

newsitems-saved specifies the maximum number of news headlines that Liberator caches in memory. When the maximum number of stored headlines is reached, the arrival of a new headline causes the oldest headline to be deleted.

Syntaxnewsitems-saved <number-of-headlines>

Type: integer

Default value: 500

news-log

news-log specifies the filename of the current news log. Logging of news headlines is disabled by default. News logs are used by Liberator to replay news headlines on startup. The conventional value for news-log is 'news.log'.

Replaying of news headlines is disabled by default. To replay news headlines, you must specify the news-log and news-replay configuration items, and optionally any of news-replay-days and news-replay-files.

Syntaxnews-log <filename>

Type: string

Default value: none (news headlines are not logged)

news-purge-days

news-purge-days specifies the number of day's worth of headlines to retain during a daily purge of news headlines from Liberator's cache, counting back from when the purge occurs. The default value is zero (days), meaning all headlines are purged.

To enable daily purging, specify news-purge-time.

Syntaxnews-purge-days <days>

Type: integer

Default value: 0 (all headlines are purged)

news-purge-time

news-purge-time schedules a time of day, in minutes after midnight, to purge old news headlines from Liberator's cache. To disable purging of news headlines, set news-purge-time to -1 (the default).

To specify the maximum age of headlines to retain during a purge, set news-purge-days.

Syntaxnews-purge-time <minutes-after-midnight>

Type: integer

Default value: -1 (purging of news headlines is disabled)

news-replay

news-replay is used in conjunction with news-replay-days to limit the age of headlines replayed from the news log on startup of Liberator.

Replaying of news headlines is disabled by default. To replay news headlines, you must specify the news-log and news-replay configuration items, and optionally any of news-replay-days and news-replay-files.

The behaviour of news-replay depends on whether its value is positive or negative.

  • when news-replay is zero or positive, news headlines are replayed that were logged more recently than news-replay minutes after midnight, news-replay-days ago.
  • when news-replay is negative, news headlines are replayed that were logged more recently than news-replay minutes before Liberator was restarted (the value of news-replay-days is ignored)

Syntaxnews-replay <minutes>

Type: integer

Default value: none (news headlines are not replayed)

Examples:

# Example 1: Replay all headlines logged after 0 minutes past midnight, 3 days ago
news-replay        0
news-replay-days   3

# Example 2: Replay all headlines logged within the last 24 hours (1440 minutes)
news-replay        -1440

news-replay-days

news-replay-days is used in conjunction with news-replay to limit the age of headlines replayed from the news log on startup of Liberator.

Replaying of news headlines is disabled by default. To replay news headlines, you must specify the news-log and news-replay configuration items, and optionally any of news-replay-days and news-replay-files.

Whether news-replay-days is used depends on the value of news-replay.

  • when news-replay is zero or positive, news headlines are replayed that were logged more recently than news-replay minutes after midnight, news-replay-days ago

  • when news-replay is negative, news headlines are replayed that were logged more recently than news-replay minutes before Liberator was restarted (the value of news-replay-days is ignored)

Syntaxnews-replay-days <days>

Type: integer

Default value: 0

Examples:

# Example 1: Replay all headlines logged after 0 minutes past midnight, 3 days ago
news-replay        0
news-replay-days   3

# Example 2: Replay all headlines logged within the last 24 hours (1440 minutes)
news-replay        -1440

news-replay-files

news-replay-files is an optional item that lists the news logs to replay on startup of Liberator. By default, only the current news log (see news-log) is replayed.

Replaying of news headlines is disabled by default. To replay news headlines, you must specify the news-log and news-replay configuration items, and optionally any of news-replay-days and news-replay-files.

The list of files must be in chronological order, with the oldest log file first and the current news log file last. The default log-cycling settings use a cyclical naming-scheme for archived logs. While it is possible to order archive logs chronologically, the order changes through the log cycle. To avoid having to edit news-replay-files each time Liberator is started, it is recommended that the log-cycling scheme for the news log be changed to one compatible with news-replay-files. The examples below show configuration settings both with and without a customised log-cycling scheme.

If a news log file is specified without an absolute path name, the order of locations in which it will be searched for is:

  1. The Liberator root directory
  2. The directory containing the current news log (see news-log)
  3. The log root directory

Syntaxnews-replay-files <file1> <file2> ... <fileN>

Type: string array

Default value: none

Examples:

If the default log-cycling settings are used, the order of files supplied to news-replay-files changes depending on the time and day of week:

Liberator restarted between... Configuration Setting (oldest log file first)
Sun 04:00  and  Mon 04:00 news-replay-files news.7 news.1 news.2 news.3 news.4 news.5 news.6 news.log
Mon 04:00  and  Tue 04:00 news-replay-files news.1 news.2 news.3 news.4 news.5 news.6 news.7 news.log
Tue 04:00  and  Wed 04:00 news-replay-files news.2 news.3 news.4 news.5 news.6 news.7 news.1 news.log
Wed 04:00  and  Thu 04:00 news-replay-files news.3 news.4 news.5 news.6 news.7 news.1 news.2 news.log
Thu 04:00  and  Fri 04:00 news-replay-files news.4 news.5 news.6 news.7 news.1 news.2 news.3 news.log
Fri 04:00  and  Sat 04:00 news-replay-files news.5 news.6 news.7 news.1 news.2 news.3 news.4 news.log
Sat 04:00  and  Sun 04:00 news-replay-files news.6 news.7 news.1 news.2 news.3 news.4 news.5 news.log

To avoid having to regularly reconfigure the value of news-replay-files before starting Liberator, you should customise the log-cycling settings for the news log. The example configuration below avoids a cyclical naming-scheme by maintaining a single, larger archive with a constant name:

# Cycle the news log every 7 days (10080 minutes) at 4 a.m. (240 minutes)
# Maintain only one archive (news.old)
add-log
    name               news_log
    time               240
    period             10080
    suffix             .old
end-log

The customised log-cycling scheme for the news log allows us to specify a fixed list of files to news-replay-files:

news-replay-files      news.old    news.log

See also: