nvchecker/README.rst

**nvchecker** (short for *new version checker*) is for checking if a new version of some software has been released.

nvchecker is now **in development**.

Dependency
==========
- Python 3
- Tornado
- All commands used in your version source files

Running
=======
To see available options::

  ./nvchecker --help

Run with one or more software version source files::

  ./nvchecker source_file_1 source_file_2 ...

You normally will like to specify some "version record files"; see below.

Version Record Files
====================
Version record files record which version of the software you know or is available. They are simple key-value pairs of ``(name, version)`` seperated by a space\ [#]_::

  fcitx 4.2.7
  google-chrome 27.0.1453.93-200836
  vim 7.3.1024

Say you've got a version record file called ``old_ver.txt`` which records all your watched software and their versions. To update it using ``nvchecker``::

  ./nvchecker --oldver old_ver.txt --newver new_ver.txt source.ini

Compare the two files for updates (assuming they are sorted alphabetically; files generated by ``nvchecker`` are already sorted)::

  comm -13 old_ver.txt new_ver.txt
  # or say that in English:
  comm -13 old_ver.txt new_ver.txt | awk '{print $1 " has updated to version " $2 "."}'
  # show both old and new versions
  join old_ver.txt new_ver.txt | awk '$2 != $3'

The ``nvtake`` Command
----------------------
This command helps to manage version record files. It reads both old and new version record files, and a list of names given on the commandline. It then update the versions of those names in the old version record file.

This helps when you have known (and processed) some of the updated software, but not all. You can tell nvchecker that via this command instead of editing the file by hand.

This command will help most if you specify where you version record files are in your config file. See below for how to use a config file.

Version Source Files
====================
The software version source files are in ini format. *Section names* is the name of the software. Following fields are used to tell nvchecker how to determine the current version of that software.

See ``sample_source.ini`` for an example.

Search in a Webpage
-------------------
Search through a specific webpage for the version string. This type of version finding has these fields:

url
  The URL of the webpage to fetch.

encoding
  (*Optional*) The character encoding of the webpage, if ``latin1`` is not appropriate.

regex
  A regular expression used to find the version string.

  It can have zero or one capture group. The capture group or the whole match is the version string.

  When multiple version strings are found, the maximum of those is chosen.

proxy
  The HTTP proxy to use. The format is ``host:port``, e.g. ``localhost:8087``. This requires `pycurl <http://pycurl.sourceforge.net/>_`.

Find with a Command
-------------------
Use a shell command line to get the version. The output is striped first, so trailing newlines do not bother.

cmd
  The command line to use. This will run with the system's standard shell (i.e. ``/bin/sh``).

Check AUR
---------
Check `Arch User Repository <https://aur.archlinux.org/>`_ for updates.

aur
  The package name in AUR. If empty, use the name of software (the *section name*).

Check GitHub
------------
Check `GitHub <https://github.com/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.

github
  The github repository, with author, e.g. ``lilydjwg/nvchecker``.

Check PyPI
----------
Check `PyPI <https://pypi.python.org/>`_ for updates.

pypi
  The name used on PyPI, e.g. ``PySide``.

Check Local Pacman Database
---------------------------
This is used when you run ``nvchecker`` on an Arch Linux system and the program always keeps up with a package in your configured repositories for `Pacman <https://wiki.archlinux.org/index.php/Pacman>`_.

pacman
  The package name to reference to.

Check Google Code (hg repository)
---------------------------------
Check a mecurial (hg) repository on `Google Code <https://code.google.com/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.

gcode_hg
  The name used on Google Code, e.g. ``chromium-compact-language-detector``.

Other
-----
More to come. Send me a patch or pull request if you can't wait and have written one yourself :-)

Config File
===========
``nvchecker`` supports a config file, which contains whatever you would give on commandline every time. This file is at ``~/.nvcheckerrc`` by default, and can be changed by the ``-c`` option. You can specify ``-c /dev/null`` to disable the default config file temporarily.

A typical config file looks like this::
    --oldver ~/.nvchecker/versionlist.txt --newver ~/.nvchecker/versionlist_new.txt

``~`` and environmental variables will be expanded. Options given on commandline override those in a config file.

Bugs
====
* Finish writing results even on Ctrl-C or other interruption.

TODO
====
* Tool to replace the ``join`` command
* Support GitHub tags

Footnotes
=========
.. [#] Note: with nvchecker <= 0.2, there are one more colon each line. You can use ``sed -i 's/://' FILES...`` to remove them.