README.md

Newman is a microframework which aims to do for email-based
applications what Rack and Sinatra have done for web programming. While our
goals may be ambitious, this project is
currently in a very early experimental stage, and is in no way safe for use in
production.

That said, Newman is already capable of doing a number of interesting things. In
particular:

A simple polling server provides a basic interface for
reading email from a single inbox and then building up a response email.

Filters are provided for handling emails based on their TO and SUBJECT fields.

Filters can also be defined for handling messages based on arbitrary
conditions evaluated against a Mail::Messsage object.

A rudimentary PStore backed storage mechanism is provided for persistence.

Basic support for maintaining persistent lists of email addresses is
provided.

We are still working on figuring out what belongs in Newman and what doesn't,
and so all of these features are subject to change or disappear entirely. But if
you have a need for this sort of tool, it's worth noting that this software
isn't entirely vaporware, and that we could use your help!

Scary Warning:

DON'T HOOK UP NEWMAN TO ANY EMAIL INBOX THAT YOU CAN'T COMPLETELY WIPE OUT EVERY TIME IT RUNS. NEWMAN WILL DELETE YOUR EMAILS!!!

For a demonstration of how Newman is used:

Check out Jester as well as some of the
simple examples in this repository.

For general discussion, questions, and ideas about Newman:

Contributing to Newman:

We do not yet have a clear roadmap or contributor guidelines, so be sure to talk
to us before working on bug fixes or patches. But assuming you do want to send
us some code, here is what you need to know:

You get to keep the copyright to your code, but you must agree to license it
under the MIT license.

Your code should come with tests. Integration tests are fine, but unit tests
would be nice where appropriate. Right now Newman is under tested and we don't
want to make that problem worse. You can of course submit a pull request for
feedback BEFORE writing tests.

Your code should be fully documented, and properly formatted for use with
Rocco. Please try to emulate the style and conventions we've been using where
possible. Do the best you can with this, and we'll help tighten up wording and
clean up formatting as needed. You can of course submit a pull request for
feedback BEFORE writing documentation.

Newman is taking a use-case oriented approach to design. Be prepared to
justify any proposed change with real or realistic scenarios, rather than
simply addressing theoretical concerns.

Versioning Policy:

We will try to follow the guidelines below when cutting new releases,
to the extent that it makes sense to do so.

Clearly mark each object that Newman provides as being part of either
the 'external API' or the 'internal API'. The external API is for
application developers, the internal API is for Newman itself as well as
extension developers

Before 1.0, allow backwards incompatible internal API changes during
every release, and allow backwards incompatible external API changes
during minor version bumps, but do not add or change external behavior
in tiny version bumps.

After 1.0, do not allow external or internal API changes during tiny
version bumps (these will be bug fixes only). Allow changes to the
internal API during minor version bumps, but maintain backwards
compatibility with the 1.0 release (i.e. things introduced after 1.0 can
be changed / removed, but things which shipped with 1.0 should stay
supported, even internally). Allow external API changes or
backwards-incompatible changes to the internals only on major version
bumps (i.e. 2.0, 3.0, etc). Use semantic versioning and declare the
external API to be the 'public' API.

We plan to get to 1.0 quickly to reach a stabilizing point for application
developers and a slower moving target for extension developers. This means
that our 1.0 release will be more of a minimum-viable product and not
necessarily a full-stack framework.

Authorship:

It is based on an assignment from Mendicant
University's January 2011 core
skills course, and was also used as a sample application for the Practicing Ruby
journal. The original inspiration for this project came from some code
written by Brent Vatne,
as well as from the general ideas behind Rack and Sinatra.

License:

Copyright (c) 2012 Gregory Brown, Eric Gjertsen, et al.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.