Extend README

Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors

---

# db-iris - Commandline Client for DB IRIS Departure Monitor

<https://finalrewind.org/projects/Travel-Status-DE-IRIS/>

db-iris is a commandline client and Perl module for the DB IRIS departure

monitor located at iris.noncd.db.de. See the [Travel::Status::DE::IRIS

homepage](https://finalrewind.org/projects/Travel-Status-DE-IRIS/) for details.

Travel::Status::DE::IRIS and the accompanying **db-iris** program provide both

human- and machine-readable access to departure data at german train stations.

They can be used by Perl scripts or modules, on the command-line, and (via JSON

output) by other programs.

It provides both human- and machine-readable access to departure data at german

train stations via text and JSON output.

Local Installation

---

## Installation

This will install db-iris and Travel::Status::DE::IRIS to a local directory.

They will not be made available system-wide; db-iris will not be added to

your program PATH. See the next section for system-wide installation.

You have four installation options:

All you need for this variant is **perl** (v5.14.2 or newer), **carton**

(packaged for many operating systems), and **libxml2** with development headers

(packaged as `libxml2-dev` on Debian-based Linux distributions).

* Nightly `.deb` builds for Debian-based distributions

* Installing the latest release from CPAN

* Installation from source

* Using a Docker image

After installing these, run the following command to install the remaining

dependencies:

Except for Docker, **db-iris** is available in your PATH after installation.

You can run `db-iris --version` to verify this. Documentation is available via

`man db-iris`.

### Nightly Builds for Debian

[lib.finalrewind.org/deb](https://lib.finalrewind.org/deb) provides Debian

packages of both development and release versions. Note that these are not part

of the official Debian repository and are not covered by its quality assurance

process.

To install the latest release, run:

```

carton install

wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_latest_all.deb

sudo dpkg -i libtravel-statusg-de-iris-perl_latest_all.deb

sudo apt --fix-broken install

rm libtravel-status-de-iris-perl_latest_all.deb

```

You are now ready to use db-iris by providing Perl with the module paths

set up by carton and Travel::Status::DE::IRIS:

For a (possibly broken) development snapshot of the Git master branch, run:

```

perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version

wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_dev_all.deb

sudo dpkg -i libtravel-status-de-iris-perl_dev_all.deb

sudo apt --fix-broken install

rm libtravel-status-de-iris-perl_dev_all.deb

```

For documentation, see `perldoc -F lib/Travel/Status/DE/IRIS.pm` and

`perldoc -F bin/db-iris`.

Note that dpkg, unlike apt, does not automatically install missing

dependencies. If a dependency is not satisfied yet, `dpkg -i` will complain

about unmet dependencies and bail out. `apt --fix-broken install` installs

these dependencies and also silently finishes the Travel::Status::DE::VRR

installation.

Uninstallation works as usual:

```

sudo apt remove libtravel-status-de-iris-perl

```

System-Wide Installation

---

### Installation from CPAN

Travel::Status::DE::IRIS releases are published on the Comprehensive Perl

Archive Network (CPAN) and can be installed using standard Perl module tools

such as `cpanminus`.

Before proceeding, ensure that you have standard build tools (i.e. make,

pkg-config and a C compiler) installed. You will also need the following

libraries with development headers:

* libdb

* libssl

* libxml2

* zlib

Now, use a tool of your choice to install the module. Minimum working example:

```

cpanm Travel::Status::DE::VRR

```

This will install db-iris and Travel::Status::DE::IRIS in system-wide

directories in `/usr/local`, allowing them to be used on the command line and

by Perl scripts without the need to specify search paths or module directories.

Building and installation is managed by the **Module::Build** perl module.

If you run this as root, it will install script and module to `/usr/local` by

default.

For this variant, you must install Module::Build and all dependencies (see the

Dependencies section below) yourself. Many of them are packaged for Debian and

other Linux distributions. Run `perl Build.PL` to check dependency availability

-- if it complains about "ERRORS/WARNINGS FOUND IN PREREQUISITES", install the

modules it mentions and run `perl Build.PL` again. Repeat this process until it

no longer complains about missing prerequisites.

### Installation from Source

You are now ready to build and install the module.

In this variant, you must ensure availability of dependencies by yourself.

You may use carton or cpanminus with the provided `Build.PL`, Module::Build's

installdeps command, or rely on the Perl modules packaged by your distribution.

On Debian 10+, all dependencies are available from the package repository.

If you downloaded a release tarball, use the following commands:

To check whether dependencies are satisfied, run:

```

perl Build.PL

```

If it complains about "... is not installed" or "ERRORS/WARNINGS FOUND IN

PREREQUISITES", it is missing dependencies.

Once all dependencies are satisfied, use Module::Build to build, test and

install the module. Testing is optional -- you may skip the "Build test"

step if you like.

If you downloaded a release tarball, proceed as follows:

```

./Build

./Build test

sudo ./Build install

```

If you are working with the git version, use these instead:

If you are using the Git repository, use the following commands:

```

perl Build.PL

./Build

./Build manifest

./Build test

sudo ./Build install

```

You can now use Travel::Status::DE::IRIS and db-iris like any other perl

module. See `man Travel::Status::DE::IRIS` and `man db-iris` for documentation.

If you do not have superuser rights or do not want to perform a system-wide

installation, you may leave out `Build install` and use **db-iris** from the

current working directory instead.

Dependencies

---

With carton:

* perl version 5.14.2 or newer

* Class::Accessor

* DateTime

* DateTime::Format::Strptime

* Geo::Distance

* List::Compare

* List::MoreUtils

* List::UtilsBy

* LWP::UserAgent

* LWP::Protocol::https

* Text::LevenshteinXS

* XML::LibXML

```

carton exec db-iris --version

```

Additional dependencies for building this module:

Otherwise (also works with carton):

* File::Slurp

* JSON

```

perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version

```

Note about Text::LevenshteinXS: This module is old and unmaintained, but

appears to be packaged for slightly more distros than its successor

Text::Levenshtein::XS. If it is not available for your distro (and you do

not wish to build it), the following drop-in replacements are available:

### Running db-iris via Docker

* Text::Levenshtein::XS

* Text::Levenshtein (about 10 times slower than the XS modules)

A db-iris image is available on Docker Hub. It is intended for testing

purposes: due to the latencies involved in spawning a container for each

db-iris invocation, and the lack of persistent caching, it is less convenient

for day-to-day usage.

To use them, run:

Installation:

```

sed -i 's/Text::LevenshteinXS/Text::Levenshtein::XS/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm

docker pull derfnull/db-iris:latest

```

or

Use it by prefixing db-iris commands with `docker run --rm

derfnull/db-iris:latest`, like so:

```

sed -i 's/Text::LevenshteinXS/Text::Levenshtein/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm

docker run --rm derfnull/db-iris:latest --version

```

Managing stations

---

Documentation is not available in this image. Please refer to the

[online db-iris manual](https://man.finalrewind.org/1/db-iris/) instead.

## Managing stations

Travel::Status::DE::IRIS needs a list of train stations to operate, which is

located in `share/stations.json`. There are two recommended editing methods.

return a `<station>` element with "name", "eva" and "ds100" attributes, you're

good to go.

Note that although EVA numbers are often identical with UIC station IDs,

there are stations where this is not the case.

Note that although EVA numbers are often identical with UIC station IDs, this

is not always the case. Please do not rely on UIC IDs when managing stations.