txt: ## dist_zef-neula-IO-Maildir.md
  # NAME
  
  `IO::Maildir` provides functions for safely dealing with maildir directories.
  
  # SYNOPSIS
  
  ```
  use IO::Maildir;
  my $inbox = maildir "~/mail/INBOX";
  $inbox.create;
  my $msg = $inbox.receive($somemail);
  
  ```
  
  # DESCRIPTION
  
  `IO::Maildir` tries to implement the [maildir](https://cr.yp.to/proto/maildir.html) spec. It can serve as a basis for mail delivery agents or mail user agents (or a mixture of both). The named `agent` parameter can be used to set the behaviour for some methods. Default behaviour can be changed by setting `$maildir-agent`.
  
  ### sub maildir
  
  ```
  sub maildir($path --> IO::Maildir)
  
  ```
  
  Returns a maildir object from `$path`. `$path` will be coerced to IO.
  
  ### maildir-agent
  
  ```
  our Agent $maildir-agent = IO::Maildir::DELIVERY
  
  ```
  
  Set this to either `IO::Maildir::DELIVERY` or `IO::Maildir::USER`. Affects behaviour of following methods:
  
  * `IO::Maildir::File`: `flag`, `move`
  * `IO::Maildir`: `walk`
  
  ## class IO::Maildir
  
  Class for maildir directories.
  
  ```
  my $maildir = IO::Maildir.new "~/Mail/INBOX";
  my $maildir = maildir "~/Mail/INBOX" # Same
  
  ```
  
  ### method create
  
  ```
  method create( --> IO::Maildir) { ... }
  
  ```
  
  Creates a new maildir directory including its cur, new and tmp subdirectories.
  
  ### method receive
  
  ```
  multi method receive($mail --> IO::Maildir::File) { ... }
  
  ```
  
  Adds a new file to the maildir. `receive` will always deliver to new and write the file to tmp first if neccessary. `$mail` may be of any type which is accepted by `IO::Path.spurt`, which are any `Cool` or `Blob` types.
  
  Up to version 0.0.2 receiving an IO object would delete the original file. This behaviour was fixed and the original file now remains after receiving.
  
  ### method walk
  
  ```
  method walk(:$all, :$agent = $maildir-agent --> Seq) { ... }
  
  ```
  
  Returns the new mails in the maildir (or all if you set it). Newest mails will be returned first.
  
  If called with `$agent = IO::Maildir::USER` it will also do the following actions:
  
  * 1. Look inside tmp and delete files older than 36 hours.
  * 1. Move files from new to cur **after** the returned Seq is consumed.
  
  ## class IO::Maildir::Files
  
  Handle for files inside a maildir.
  
  ```
  #Create from IO::Path
  my $file = IO::Maildir::File.new( path => "~/Mail/INBOX/cur/uniquefilename:2,".IO );
  #Create from maildir
  my $file = IO::Maildir::File.new( dir => $maildir, name => "uniquefilename:2," );
  
  ```
  
  Usually you don't need to do anything of the above, since you will receive your `IO::Maildir::File` objects from `IO::Maildir`s methods.
  
  ### attribute dir
  
  ```
  has IO::Maildir $.dir
  
  ```
  
  Points to the maildir containing this file.
  
  ### attribute name
  
  ```
  has $.name
  
  ```
  
  Complete file name including flags and stuff.
  
  ### method IO
  
  ```
  method IO( --> IO ) { ... }
  
  ```
  
  Returns the `IO::Path` object pointing to the file.
  
  ### method flags
  
  ```
  method flags( --> Set ) { ... }
  
  ```
  
  Returns the `Set` of flags set for this file.
  
  ### method flag
  
  ```
  multi method flag(:$agent = $maildir-agent, *%flags)
  multi method flag(
      %flags where *.keys.Set ⊆ <P R S T D>.Set,
      :$agent = $maildir-agent)
  
  ```
  
  Use this to set flags. Fails if `$agent` is set to `IO::Maildir::DELIVERY`. This will also move the file to cur, because it has been seen by the MUA.
  
  ### method move
  
  ```
  multi method move(IO::Maildir $maildir, Agent :$agent = $maildir-agent --> IO::Maildir::File) { ... }
  multi method move (IO $iodir, Agent :$agent = $maildir-agent --> IO::Maildir::File) { ... }
  
  ```
  
  Moves the file to a different maildir and returns the updated file-handle. If called in `IO::Maildir::DELIVERY` mode, the file will be moved to new and old flags will be removed. If called in `IO::Maildir::USER` mode, it will be moved to cur and flags will be preserved.
  
  # AUTHOR
  
  neula [thomas@famsim.de](mailto:thomas@famsim.de)
  
  Source can be located at: <https://github.com/neula/IO-Maildir> . Comments and Pull Requests are welcome.
  
  # LICENSE
  
  This library is free software; you may redistribute or modify it under the Artistic License 2.0.
  