JHC - Jabber Humane Clock.
Copyright (C) 2007  Denis Nelubin aka Gelin

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

http://gelin.ru
mailto:den@gelin.ru
xmpp:gelin@jabber.ru?message


The idea to write the time "in a humane way" belongs to Art. Lebedev Studio.
Their the Verbarius clock (http://store.artlebedev.com/catalog/office/verbarius/)
does it.

The idea is implemented as Jabber bot, which can runs as separate Jabber entity
and sends current time message "in a humane way" to everybody in it's roster who's
online. Or it can runs as bot in a multi-user conference and sends time message to
conference room. The period of sending message is defined as command line argument.


DEPENDENCES

JHC requires following programs and packages for correct work:
    - Python >= 2.5  (It's written on Python)
    - SQLite >= 3    (libsqlite3-0, sqlite3 Ubuntu packages)
    - sqlite3 Python module     (python-pysqlite1.1 Ubuntu package)
    - xmpp Python module    (python-xmpp Ubuntu package)


INSTALLATION

Get zip archive with JHC source code. Unpack it to some directory.

Run as root:
    python setup.py install
this will install jhc package to your Python system libraries.

Now you can run jhc-cli.py or jhc-bot.py scripts from bin/ directory.


USAGE

You can run bin/jhc-cli.py or bin/jhc-bot.py scripts prepending their names by
'python' in command line. Or just make them executable.

Both scripts takes many command line options. Some options are required.
You can put all options into file (with possible comments) and provide this
file as argument.

jhc-cli.py prints time in humane format to command line.

It takes two options:
  -f FILE, --database-file=FILE
                        file with SQLite database with time strings
                        this option is required
  -t HH:MM, --time=HH:MM
                        display message for time in format HH:MM
                        if you don't provide time, current time is displayed

data/ directory contains databases with time strings. ru.db contains
Russian times.

Example:
    python bin/jhc-cli.py -f data/ru.db
    python bin/jhc-cli.py -f data/ru.db -t 7:00

jhc-bot.py runs Jabber bot.

It takes many options:
  time string database options:
    -f FILE, --database-file=FILE
                        file with SQLite database with time strings
                        this is required option

  connection to Jabber server options:
    -j JID, --jid=JID   JID which is used to connect to Jabber server
                        this is required option, or you can provide
                        username and server as separate arguments,
                        but only here your can provide connection resource
    -p PASSWORD, --password=PASSWORD
                        password which is used to connect to Jabber server
                        this is required option
    --user=USER         user name (if differs from JID node part)
    --server=HOST       Jabber server host (if differs from JID domain part)
    --port=PORT         Jabber server port (if non-standard)
    --secure=1|0        force to enable (1) or disable (0) SSL/TLS encryption

  bot behaviour options:
    -c ROOM@MUC/NICK, --join-conference=ROOM@MUC/NICK
                        join conference on startup (can use many times)
    --default-nick=NICK
                        nick which is used when bot is invited to conference
                        (default: 'timebot')
    --no-roster         do not send time message to JIDs from roster
    -t HH:MM, --time=HH:MM
                        start to send time message from specified time
                        (default: '00:00')
    -i MINUTES, --interval=MINUTES
                        interval to send time message in minutes (default:
                        '30')

  proxy options:
    --proxy-host=HOST   proxy host (if need)
    --proxy-port=PORT   proxy port (if need)
    --proxy-user=USER   proxy username (if need)
    --proxy-password=PASSWORD
                        proxy password (if need)

There is sample configuration file with all options described:
etc/jhc-test.cfg

To enable debug mode you can setup LOG_LEVEL environment variable:
    export LOG_LEVEL=DEBUG

To run bot as daemon you can use nohup command:
    nohup bin/jhc-bot.py etc/jhc-test.cfg 2>&1 &

When started, bot send time message to every roster contacts which are online.
To disable such functionality, provide --no-roster option.

When started, bot joins to conferences which are listed as parameters
to --join-conference option. This option can be used many times, so bot can
join to many conferences. You can provide bot's nick as resource part of
conference JID.

On joining to conference bot sends message with current time. If some
conference occupant says "/time", bot sends message with current time again.

You can invite bot to any conference. It accepts invitation and joins to
conference. After it behave themself as joining by --join-conference command
line options.

Any Jabber entity can send message to bot. It always replies with current time
message.

Every half an hour (or you can specify start time and interval of action by
--time and --interval options) bot:
    - sends time message to every contacts in roster which are online
      (disabled by --no-roster option);
    - sends time message to every conference rooms where bot is joined.


TIME MESSAGES

Time messages are saved in SQLite 3 database. You can specify you own messages
on your language.

Database contains only one table with following format:
    CREATE TABLE time_string (
        hour INTEGER NOT NULL,
        minute INTEGER NOT NULL,
        string TEXT NOT NULL,
        language CHAR(2) DEFAULT NULL
    );
"hour" and "minute" are keys for selecting message. You can specify multiple
messages with the same key, one of messages with the same key will be randomly
selected.
"string" is a message themself.
"language" is a message language identificator, not used now.

You can prepare you messages as .CSV file and insert them into database. As
example, see format of data/csv/ru.csv file. Time messages in CSV file must
be encoded in UTF-8.

Create new database:
    sqlite3 -init data/sql/create.sql data/new.db
Insert strings:
    bin/csv2db.py data/csv/new.csv data/new.db