diff --git a/README.md b/README.md index 7847cbe..31a3fe7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,39 @@ -[![Build Status](https://app.travis-ci.com/dburkart/check-sieve.svg?branch=master)](https://app.travis-ci.com/dburkart/check-sieve) +
+

+ check-sieve +
+ + Because breaking your sieve in production sucks. + +

+
-### check-sieve +
-This project aims to make checking mail sieve syntax easy and painless. Because breaking your sieve in production sucks. +[![badge-license]][url-license] +[![badge-contributors]][url-contributors] +![badge-language] +[![badge-tests]][url-tests] +[![badge-last-release]][url-last-release] + +
+ +[badge-license]: https://img.shields.io/github/license/dburkart/check-sieve?style=for-the-badge +[badge-contributors]: https://img.shields.io/github/contributors/dburkart/check-sieve?style=for-the-badge +[badge-language]: https://img.shields.io/github/languages/top/dburkart/check-sieve?style=for-the-badge +[badge-tests]: https://img.shields.io/github/actions/workflow/status/dburkart/check-sieve/c-cpp.yml?style=for-the-badge&label=Tests +[badge-last-release]: https://img.shields.io/github/release-date/dburkart/check-sieve?style=for-the-badge&label=Last%20Release + +[url-license]: ./LICENSE +[url-contributors]: https://github.com/dburkart/check-sieve/graphs/contributors +[url-tests]: https://github.com/dburkart/check-sieve/actions +[url-last-release]: https://github.com/dburkart/check-sieve/releases/latest + + +This project aims to make checking mail [Sieve][wiki-sieve] syntax easy and painless. +_Because breaking your sieve in production sucks._ + +[wiki-sieve]: https://en.wikipedia.org/wiki/Sieve_(mail_filtering_language) Particular attention is paid to the quality of errors generated. For example: @@ -20,23 +51,117 @@ Usage: convert For a web-based demonstration of check-sieve which is entirely browser-based, visit https://checksieve.com. -#### Build Dependencies +## Usage +``` +Usage: check-sieve [options] file1 [file2 ...] + +Options: + -h, --help Show this message + --max-list-length N Flag lists over a certain length (default: none) + --server : Only allow capabilities advertised by the specified + server. + --trace-parser Trace the operation of the parser + --trace-scanner Trace the operation of the scanner + --trace-tree Trace the abstract-syntax-tree + --version Print out version information +``` + +## Features +### Supported RFCs +* Sieve: An Email Filtering Language ([RFC 5228](https://tools.ietf.org/html/rfc5228)) +* Variables Extension ([RFC 5229](https://tools.ietf.org/html/rfc5229)) +* Date and Index Extensions ([RFC 5260](https://tools.ietf.org/html/rfc5260)) +* Vacation Extension ([RFC 5230](https://tools.ietf.org/html/rfc5230)) +* Include Extension ([RFC 6609](https://tools.ietf.org/html/rfc6609)) +* Copying Without Side Effects ([RFC 3894](https://tools.ietf.org/html/rfc3894)) +* Reject and Extended Reject Extensions ([RFC 5429](https://tools.ietf.org/html/rfc5429)) +* Body Extension ([RFC 5173](https://tools.ietf.org/html/rfc5173)) +* Relational Extension ([RFC 5231](https://tools.ietf.org/html/rfc5231)) +* MIME Part Tests, Iteration, Extraction, Replacement, and Enclosure ([RFC 5703](https://tools.ietf.org/html/rfc5703)) +* Imap4flags Extension ([RFC 5232](https://tools.ietf.org/html/rfc5232)) +* Editheader Extension ([RFC 5293](https://tools.ietf.org/html/rfc5293)) +* Regex Extension ([DRAFT](https://tools.ietf.org/html/draft-ietf-sieve-regex-01)) +* Spamtest and Virustest Extensions ([RFC 5235](https://tools.ietf.org/html/rfc5235)) +* Extensions for Notifications ([RFC 5435](https://tools.ietf.org/html/rfc5435)) +* Subaddress Extension ([RFC 5233](https://tools.ietf.org/html/rfc5233)) +* Ihave Extension ([RFC 5463](https://tools.ietf.org/html/rfc5463)) +* Environment Extension ([RFC 5183](https://tools.ietf.org/html/rfc5183)) +* Sieve Notification Mechanism: mailto ([RFC 5436](https://tools.ietf.org/html/rfc5436)) +* Internet Message Access Protocol (IMAP) Events ([RFC 6785](https://tools.ietf.org/html/rfc6785)) +* Converting Messages before Delivery ([RFC 6558](https://tools.ietf.org/html/rfc6558)) +* Proton Expiration Extension ([vnd.proton.expire](https://proton.me/support/sieve-advanced-custom-filters#managing-expiration)) +* Proton Eval Extension ([vnd.proton.eval](https://proton.me/support/sieve-advanced-custom-filters#transforming-variables)) + +> [!NOTE] +> If you find any discrepancies with these RFCs, +> have a request for an RFC not included, +> or have test-cases that should work but don't, +> please [file an issue][file-issue]. + +[file-issue]: https://github.com/dburkart/check-sieve/issues/new -`check-sieve` minimally depends on having a modern C++ compiler. On BSD-like systems such as FreeBSD, you'll -also need gmake installed. +## Development +### Dependencies +`check-sieve` minimally depends on having a modern C++ compiler and the +[Make][make] build automation software. -#### Development Dependencies +On BSD-like systems such as FreeBSD, the [`gmake`][gnu-make] tool is required. -The following dependencies are required in order to develop check-sieve: +[make]: https://en.wikipedia.org/wiki/Make_(software) +[gnu-make]: https://www.gnu.org/software/make/ -* bison >= v3.0.4 -* flex >= v2.5.35 -* Python >= 3.7 +Building `check-sieve` only depends on those aforementioned tools. Developing +`check-sieve` requires addition dependencies: + +* [GNU Bison][bison] >= v3.0.4 +* [Flex][flex] >= v2.5.35 +* [Python][python] >= 3.7 * Python development headers (for testing) -Additionally, if you want to generate a javascript library, you'll need emscripten installed. +Additionally, [Emscripten][emscripten] is required to generate the Check Sieve JavaScript library. + +[bison]: https://www.gnu.org/software/bison/ +[flex]: https://github.com/westes/flex +[python]: https://www.python.org/ +[emscripten]: https://emscripten.org/ + +#### Installing dependencies +
+Ubuntu and Debian-based distributions +

+ +```bash +# Synchronize mirrors +sudo apt-get update -#### Compiling +# Core development dependencies +sudo apt-get install make gcc g++ bison flex python3 libpython3-dev + +# JavaScript dependencies +sudo apt-get install emscripten +``` + +

+
+ +
+Arch Linux +

+ +```bash +# Synchronize mirrors, and +# Core development dependencies +sudo pacman -Syu make gcc bison flex python + +# JavaScript dependencies +sudo pacman -Sy emscripten +``` + +

+
+ + +### Compiling At the moment, there are four targets for this project: @@ -64,42 +189,10 @@ to the desired location. * Arch Linux ([community](https://archlinux.org/packages/extra/x86_64/check-sieve/) repository) - ##### Snap -To build the snap, run `snapcraft`. -Installation of the locally-built snap requires the following: + +Installation of the latest edge snap from snapcraft can be done with the following command: ``` -sudo snap install --dangerous --devmode check-sieve_X.X_amd64.snap +snap install --edge check-sieve ``` -#### Supported RFCs - -Currently, the supported RFCs are: - -* Sieve: An Email Filtering Language ([RFC 5228](https://tools.ietf.org/html/rfc5228)) -* Variables Extension ([RFC 5229](https://tools.ietf.org/html/rfc5229)) -* Date and Index Extensions ([RFC 5260](https://tools.ietf.org/html/rfc5260)) -* Vacation Extension ([RFC 5230](https://tools.ietf.org/html/rfc5230)) -* Include Extension ([RFC 6609](https://tools.ietf.org/html/rfc6609)) -* Copying Without Side Effects ([RFC 3894](https://tools.ietf.org/html/rfc3894)) -* Reject and Extended Reject Extensions ([RFC 5429](https://tools.ietf.org/html/rfc5429)) -* Body Extension ([RFC 5173](https://tools.ietf.org/html/rfc5173)) -* Relational Extension ([RFC 5231](https://tools.ietf.org/html/rfc5231)) -* MIME Part Tests, Iteration, Extraction, Replacement, and Enclosure ([RFC 5703](https://tools.ietf.org/html/rfc5703)) -* Imap4flags Extension ([RFC 5232](https://tools.ietf.org/html/rfc5232)) -* Editheader Extension ([RFC 5293](https://tools.ietf.org/html/rfc5293)) -* Regex Extension ([DRAFT](https://tools.ietf.org/html/draft-ietf-sieve-regex-01)) -* Spamtest and Virustest Extensions ([RFC 5235](https://tools.ietf.org/html/rfc5235)) -* Extensions for Notifications ([RFC 5435](https://tools.ietf.org/html/rfc5435)) -* Subaddress Extension ([RFC 5233](https://tools.ietf.org/html/rfc5233)) -* Ihave Extension ([RFC 5463](https://tools.ietf.org/html/rfc5463)) -* Environment Extension ([RFC 5183](https://tools.ietf.org/html/rfc5183)) -* Sieve Notification Mechanism: mailto ([RFC 5436](https://tools.ietf.org/html/rfc5436)) -* Internet Message Access Protocol (IMAP) Events ([RFC 6785](https://tools.ietf.org/html/rfc6785)) -* Converting Messages before Delivery ([RFC 6558](https://tools.ietf.org/html/rfc6558)) -* Externally Stored Lists ([RFC 6134](https://tools.ietf.org/html/rfc6134)) -* Proton Expiration Extension ([vnd.proton.expire](https://proton.me/support/sieve-advanced-custom-filters#managing-expiration)) -* Proton Eval Extension ([vnd.proton.eval](https://proton.me/support/sieve-advanced-custom-filters#transforming-variables)) - -If you find any discrepancies with these RFCs, or have reduced test-cases that should work but don't, please file an -issue. If there's an RFC that isn't supported that you want, file an issue!