<commit_before># MailHooker #

MailHooker is small utility, written in perl, that allows a user to hook a
command to execute when new email is received.

## Dependencies ##

- Perl v5.18 or greater *May be work with older versions, but no promises*
- [Mail::IMAPClient](http://search.cpan.org/~plobbes/Mail-IMAPClient-3.35/)
- [Perl YAML](http://search.cpan.org/dist/YAML/)

## Configuration ##

At the root of the project is a file named config.yml.sample. Edit the
settings to meet your needs, and rename the file to config.yml.

Seeing as how the config.yml file contains your account information, I would
advise changing the file permissions to prevent other user's from reading it.

    chmod 600 config.yml

If this solution isn't secure enough for you, see below for a solution
involving encryption with gpg.

## Running the Script ##

**Before running the script, ensure that all dependencies are installed**

### Using the Standard Config.yml Location ###

If you've created your config.yml file in the project's root directory, you
can run the script with:

    perl /path/to/mail_hooker/src/mail_hooker.pl

### Using a Non-Standard Config File Location ###

If STDIN is provided, MailHooker will assume this is your configuration. Thus,
if you'd like to create your configuration file in a non-standard location you
can do so with the following:

    perl /path/to/mail_hooker/src/mail_hooker.pl < /path/to/my/config.yml

### Running Alongside Another Application ###

MailHooker can be tied into the process ID of another command. If the other
command finishes, or is killed, MailHooker will detect this and exit. This
feature allows a user to run MailHooker as though it were dependant on
another program.

For example, if you only want MailHooker to run when you are using mutt,
you could create the following wrapper script:

    #!/usr/bash

    # Enable job control so that we can use 'fg'
    set -m

    # Start the mutt email client
    mutt &

    mutt_pid=$!
    perl /path/to/mail_hooker/src/mail_hooker.pl $mutt_pid &

    fg 1 # Bring mutt to the foreground (our first job)

When you run this script, mutt will open with MailHooker in the background.
When mutt is closed, MailHooker will stop automatically.

### Encrypting Your Config File with GPG ###

If you are a real security stickler, you can encrypt your config file with
GPG, and run the decrypter when calling MailHooker.

    gpg --batch -d config.yml.gpg | perl src/mail_hooker.pl

GPG will prompt you for your password, and then pass the decrypted file
straight into MailHooker.

## Contributing ##

If you are interesting in contributing to MailHooker please ensure your
commits follow a few simple guidelines.

- Write tests, both for new functionality and for bug fixes.
- Avoid trailing whitespace.
- Format commit messages in the imperative present tense.

## License ##
<commit_msg>Clean up the README file<commit_after># MailHooker #

MailHooker is small utility, written in perl, that allows a user to hook a
command to execute when new email is received.

## Dependencies ##

- Perl v5.18 or greater *May be work with older versions, but no promises*
- [Mail::IMAPClient](http://search.cpan.org/~plobbes/Mail-IMAPClient-3.35/)
- [Perl YAML](http://search.cpan.org/dist/YAML/)

## Configuration ##

At the root of the project is a file named config.yml.sample. Edit the
settings to meet your needs, and rename the file to config.yml.

Seeing as how the config.yml file contains your account information, I would
advise changing the file permissions to prevent other user's from reading it.

    chmod 600 config.yml

If this solution isn't secure enough for you, see below for a solution
involving encryption with gpg.

## Running the Script ##

**Before running the script, ensure that all dependencies are installed**

### Using the Standard Config.yml Location ###

If you've created your config.yml file in the project's root directory, you
can run the script with:

    perl /path/to/mail_hooker/src/mail_hooker.pl

### Using a Non-Standard Config File Location ###

If STDIN is provided, MailHooker will assume this is your configuration. Thus,
if you'd like to create your configuration file in a non-standard location you
can do so and then run MailHooker with the following:

    perl /path/to/mail_hooker/src/mail_hooker.pl < /path/to/my/config.yml

### Running Alongside Another Application ###

MailHooker can be tied into the process ID of another command. If the other
command finishes, or is killed, MailHooker will detect this and exit. This
feature allows a user to run MailHooker as though it were dependant on
another program.

For example, if you only want MailHooker to run when you are using mutt,
you could create the following wrapper script:

    #!/bin/bash

    # Enable job control so that we can use 'fg'
    set -m

    # Start the mutt email client
    mutt &

    mutt_pid=$!
    perl /path/to/mail_hooker/src/mail_hooker.pl $mutt_pid &

    fg 1 # Bring mutt to the foreground (our first job)

When you run this script, mutt will open with MailHooker running in the
background. When mutt is closed, MailHooker will stop automatically.

### Encrypting Your Config File with GPG ###

If you are a real security stickler, you can encrypt your config file with
GPG, and decrypt the data before passing it to MailHooker.

    gpg --batch -d config.yml.gpg | perl src/mail_hooker.pl

GPG will prompt you for your password, and then pass the decrypted config data
straight into MailHooker.

## Contributing ##

If you are interesting in contributing to MailHooker please ensure your
commits follow a few simple guidelines.

- Write tests, both for new functionality and for bug fixes.
- Avoid trailing whitespace.
- Format commit messages in the imperative present tense.

## License ##

{'fraction_non_alphanumeric': 0.0674814942330866, 'fraction_numerical': 0.003442933379239112, 'mean_word_length': 3.853801169590643, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5117713', 'n_tokens_mistral': 1692, 'n_tokens_neox': 1611, 'n_words': 804}