#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass article
\use_default_options true
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans helvet
\font_typewriter default
\font_default_family sfdefault
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize 12
\spacing single
\use_hyperref false
\papersize a4paper
\use_geometry true
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 2cm
\topmargin 2cm
\rightmargin 2cm
\bottommargin 2cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Yolk Manual
\end_layout

\begin_layout Date
Revised December 11th.
 2012
\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Part
General Information
\end_layout

\begin_layout Section
Copyright and License
\end_layout

\begin_layout Standard
This document is copyright (C) 2010-, Thomas Løcke.
 You may copy this document, in whole or in part, in any form or by any
 means, as is or with alterations, provided that (1) alterations are clearly
 marked as alterations and (2) this copyright notice is included unmodified
 in any copy.
\end_layout

\begin_layout Standard
Yolk is GPLv3 software.
 You should have received a copy of the GNU General Public License and a
 copy of the GCC Runtime Library Exception along with this program; see
 the files COPYING3 and COPYING.RUNTIME respectively.
 If not, see 
\begin_inset CommandInset href
LatexCommand href
name "http://www.gnu.org/licenses/"
target "http://www.gnu.org/licenses/"

\end_inset

.
 
\end_layout

\begin_layout Section
What is Yolk?
\end_layout

\begin_layout Standard
Yolk is a collection of packages that aim to help build solid web-applications
 using Ada.
 Yolk itself doesn't do a whole lot that can't be accomplished simply by
 using 
\begin_inset CommandInset href
LatexCommand href
name "AWS"
target "http://libre.adacore.com/libre/tools/aws/"

\end_inset

 and the 
\begin_inset CommandInset href
LatexCommand href
name "GNAT Component Collection (GNATcoll)"
target "http://libre.adacore.com/libre/tools/gnat-component-collection/"

\end_inset

, but it does make the job of building complete web-applications a bit simpler.
 Things like changing user for the running application, catching POSIX signals
 such as SIGKILL, sending log data to syslogd, adding basic static content
 handlers, creating and starting/stopping an AWS powered HTTP server and
 building Atom syndication XML are all made a bit easier with Yolk.
\end_layout

\begin_layout Standard
A Yolk application is in reality an AWS application, with some sugar added,
 so you're not really building a Yolk web-application, as much as you're
 building an AWS web-application.
 What I'm getting at, is that you need to understand how to use AWS, in
 order for Yolk to make any kind of sense.
 What you get when using Yolk is the little things that AWS does not readily
 provide.
\end_layout

\begin_layout Subsection
The Yolk demo application
\end_layout

\begin_layout Standard
Reading this manual will of course (I hope!) help you understand how to
 use Yolk, but please consider taking a closer look at the Yolk demo application
 to get a feel for how Yolk is actually used.
 The demo is heavily commented, so it should be fairly easy to understand
 what's going on.
 The demo application is also very suitable as a foundation for other AWS/Yolk
 applications.
\end_layout

\begin_layout Standard
It is much easier to show how to use Yolk, than it is to write down all
 possible usage scenarios.
 With the combination of this manual, the Yolk source files and the demo
 application, you should be able to make full use of the Yolk packages in
 your own applications.
\end_layout

\begin_layout Subsection
The source code
\end_layout

\begin_layout Standard
The Yolk source code is the best documentation there is.
 This document is never going to be as comprehensive as the actual source,
 so I'll strongly suggest having the source code available as you read this
 document.
 What you will find in this document are short descriptions of what a package
 is meant to do and perhaps small usage examples, not a complete rundown
 of every type and procedure in a package.
\end_layout

\begin_layout Subsection
Building and installing Yolk
\end_layout

\begin_layout Standard
See the README and INSTALL files.
 These are found in the Yolk root directory.
\end_layout

\begin_layout Subsection
The files Yolk depend upon
\end_layout

\begin_layout Standard
When you read this document and the Yolk source code, you'll notice that
 quite a few packages depend on various files being available at specified
 locations.
 This is for example the case with the 
\emph on
Yolk.Whoops
\emph default
 package that expects its template file to be found at the path 
\emph on
templates/system/500.tmpl
\end_layout

\begin_layout Standard
All such 
\begin_inset Quotes eld
\end_inset

dependencies
\begin_inset Quotes erd
\end_inset

 will of course be noted accordingly as we go along, but instead of forgetting
 one or more in your own application, I'd much rather encourage using the
 demo application as a foundation for your own applications, since all these
 fixed paths and files has been properly added to the demo.
\end_layout

\begin_layout Standard
I also recommend compiling and running the demo, to make sure your Yolk
 install is working as intended.
 Just read the 
\emph on
demo/README
\emph default
 and 
\emph on
demo/INSTALL
\emph default
 files for instructions on how to get it up and running.
\end_layout

\begin_layout Subsection
The Yolk packages naming
\end_layout

\begin_layout Standard
The Yolk packages are pretty diverse, ranging from process control to sending
 email.
 I've tried naming them as sensibly as possible, in the hope that the package
 names alone give away their function.
 If I've failed, well, you're just going to have to refer to this document
 or take a look at the source for yourself.
\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Part
The Yolk Packages
\end_layout

\begin_layout Section
Yolk
\end_layout

\begin_layout Standard
The Yolk main package currently only contain only a few things: The Yolk
 
\emph on
Version
\emph default
 string, a 
\emph on
Config_File
\emph default
 function to get the location of the configuration file and a 
\emph on
PID_File
\emph default
 function to get the location of the PID file.
 These are used in a few places, for example in the 
\emph on
directory.tmpl
\emph default
 template file (the version string), in the 
\emph on
Yolk.Configuration
\emph default
 package (the 
\emph on
Config_File
\emph default
 function) and in the 
\emph on
Yolk.Process_Control
\emph default
 package (the 
\emph on
PID_File
\emph default
 function).
\end_layout

\begin_layout Standard
All Yolk applications accepts two commandline arguments:
\end_layout

\begin_layout Itemize

\emph on
--yolk-config-file
\emph default
 : Defines the location of the configuration file.
 If empty or not set, then use the default location 
\emph on
configuration/config.ini
\emph default
.
\end_layout

\begin_layout Itemize

\emph on
--pid-file
\emph default
 : Defines the location of the PID file.
 If empty or not set, then don't write a PID file.
 Note that if you use the 
\emph on
extras/rc.yolk
\emph default
 script to control your application, then this is handled for you transparently.
\end_layout

\begin_layout Section
Yolk.Cache.Discrete_Keys
\end_layout

\begin_layout Standard
If a piece of data doesn't change very often and it is expensive to build,
 then caching it might be worthwhile.
 Instead of going to a file or database on every hit, you simply go to the
 cache and grab the latest version from there.
 This is 
\series bold
\emph on
very
\series default
\emph default
 fast, at the cost of some memory.
\end_layout

\begin_layout Standard
If you know exactly what you want to cache, the 
\emph on
Yolk.Cache.Discrete_Keys
\emph default
 package might be just what you need.
\end_layout

\begin_layout Subsection
The generic formal parameters
\end_layout

\begin_layout Standard
These are:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

generic
\end_layout

\begin_layout Plain Layout

   type Key_Type is (<>);
\end_layout

\begin_layout Plain Layout

   type Element_Type is private;
\end_layout

\begin_layout Plain Layout

   Max_Element_Age : Duration := 3600.0;
\end_layout

\begin_layout Plain Layout

package Yolk.Cache.Discrete_Keys is
\end_layout

\begin_layout Plain Layout

...
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
Max_Element_Age
\emph default
 defaults to one hour.
 You should obviously set this to whatever suits your needs.
 This timer is used for all content in the cache.
 You cannot set this individually for each element.
\end_layout

\begin_layout Subsection
Instantiation
\end_layout

\begin_layout Standard
If for example we have two different sets of data (Foo and Bar) that are
 expensive to build, we can instantiate a 
\emph on
Discrete_Keys
\emph default
 package to handle this:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

type Cache_Keys is (Foo, Bar);
\end_layout

\begin_layout Plain Layout

package My_Cache is new Yolk.Cache.Discrete_Keys
\end_layout

\begin_layout Plain Layout

  (Key_Type     => Cache_Keys,
\end_layout

\begin_layout Plain Layout

   Element_Type => Unbounded_String);
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
And that is all.
 We now have a 
\emph on
My_Cache
\emph default
 object that can hold two objects: 
\emph on
Foo
\emph default
 and 
\emph on
Bar
\emph default
.
 These are of the type 
\emph on
Unbounded_String
\emph default
 and they have a 
\emph on
Max_Element_Age
\emph default
 of 3600.0 seconds.
\end_layout

\begin_layout Subsection
Writing to the cache
\end_layout

\begin_layout Standard
Before we can read something from the cache, we must first write something
 to it:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

declare
\end_layout

\begin_layout Plain Layout

   Foo_Value : Unbounded_String := To_Unbounded_String ("Foo");
\end_layout

\begin_layout Plain Layout

begin
\end_layout

\begin_layout Plain Layout

   My_Cache.Write (Key   => Foo,
\end_layout

\begin_layout Plain Layout

                   Value => Foo_Value);
\end_layout

\begin_layout Plain Layout

end;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
That is all it takes: 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset

 is now safely tucked away in the 
\emph on
My_Cache
\emph default
 object, and will be so for 3600.0 seconds.
 Calling 
\emph on
Write
\emph default
 with the 
\emph on
Foo 
\emph default
key will always overwrite earlier written 
\emph on
Foo
\emph default
 elements, no matter their age.
\end_layout

\begin_layout Subsection
Reading from the cache
\end_layout

\begin_layout Standard
A cache obviously only makes sense if you intend to read from it.
 In our case we want to get our hands on the previously written 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset

 value:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

declare
\end_layout

\begin_layout Plain Layout

   Valid : Boolean := False;
\end_layout

\begin_layout Plain Layout

   Value : Unbounded_String;
\end_layout

\begin_layout Plain Layout

begin
\end_layout

\begin_layout Plain Layout

   My_Cache.Read (Key      => Foo,
\end_layout

\begin_layout Plain Layout

                  Is_Valid => Valid,
\end_layout

\begin_layout Plain Layout

                  Value    => Value);
\end_layout

\begin_layout Plain Layout

   if Valid then
\end_layout

\begin_layout Plain Layout

      --  do something interesting with the data
\end_layout

\begin_layout Plain Layout

   else
\end_layout

\begin_layout Plain Layout

      --  the Foo data is invalid.
\end_layout

\begin_layout Plain Layout

   end if;
\end_layout

\begin_layout Plain Layout

end;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
In order for an element to be valid (the
\emph on
 Is_Valid
\emph default
 parameter is true), it must:
\end_layout

\begin_layout Enumerate
have been added to the cache in the first place
\end_layout

\begin_layout Enumerate
be younger than 
\emph on
Max_Element_Age
\end_layout

\begin_layout Standard
If 
\emph on
Is_Valid
\emph default
 is 
\emph on
False
\emph default
, then 
\emph on
Value
\emph default
 is undefined.
 Note that if 
\emph on
Is_Valid
\emph default
 is 
\emph on
False
\emph default
 then 
\emph on
Key
\emph default
 is removed from the cache, if it exists.
\end_layout

\begin_layout Subsection
Checking if a key is valid
\end_layout

\begin_layout Standard
If you need to check whether a specific key exists in the cache and is valid,
 then you must use the 
\emph on
Is_Valid
\emph default
 function.
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

if My_Cache.Is_Valid (Foo) then
\end_layout

\begin_layout Plain Layout

   --  Foo is good!
\end_layout

\begin_layout Plain Layout

else
\end_layout

\begin_layout Plain Layout

   --  Foo is bad!
\end_layout

\begin_layout Plain Layout

end if;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
This follows the same rules as the 
\emph on
Is_Valid
\emph default
 parameter for the 
\emph on
Read
\emph default
 procedure.
\end_layout

\begin_layout Subsection
Clearing keys and the entire cache
\end_layout

\begin_layout Standard
For clearing of keys and the entire cache we have, naturally, two 
\emph on
Clear
\emph default
 procedures:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

-- First we clear the Foo key
\end_layout

\begin_layout Plain Layout

My_Cache.Clear (Key => Foo);
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

--  And then we clear the entire cache
\end_layout

\begin_layout Plain Layout

My_Cache.Clear;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
And that's all it takes.
\end_layout

\begin_layout Subsection
Cleanup - Getting rid of stale elements
\end_layout

\begin_layout Standard
Calling Cleanup will delete all stale elements from the cache:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

My_Cache.Cleanup;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that this is potentially a very expensive operation if the cache is
 large, as the entire cache is iterated and every element tested for its
 age.
 Use with care.
\end_layout

\begin_layout Section
Yolk.Cache.String_Keys
\end_layout

\begin_layout Standard
This package is almost similar to the 
\emph on
Yolk.Cache.Discrete_Keys
\emph default
 package.
 The biggest difference is that where the 
\emph on
Discrete_Keys
\emph default
 cache package requires that you define a type for the keys, this package
 use regular 
\emph on
String
\emph default
 as keys.
\end_layout

\begin_layout Standard
The implications of this difference between the two cache packages are subtle.
 Both have the same 
\emph on
Read
\emph default
, 
\emph on
Write
\emph default
, 
\emph on
Is_Valid
\emph default
 and 
\emph on
Clear
\emph default
 procedures and functions, so in that sense the two packages are the same.
 The biggest difference lies in the available generic formal parameters
 and the functionality of the 
\emph on
Cleanup
\emph default
 procedure.
\end_layout

\begin_layout Subsection
The generic formal parameters
\end_layout

\begin_layout Standard
These are:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

generic
\end_layout

\begin_layout Plain Layout

   type Element_Type is private;
\end_layout

\begin_layout Plain Layout

   Cleanup_Size      : Positive := 200;
\end_layout

\begin_layout Plain Layout

   Cleanup_On_Write  : Boolean  := True;
\end_layout

\begin_layout Plain Layout

   Max_Element_Age   : Duration := 3600.0;
\end_layout

\begin_layout Plain Layout

   Reserved_Capacity : Positive := 100;
\end_layout

\begin_layout Plain Layout

package Yolk.Cache.Discrete_Keys is
\end_layout

\begin_layout Plain Layout

...
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
When the amount of elements in the cache >= 
\emph on
Cleanup_Size
\emph default
, then the 
\emph on
Cleanup
\emph default
 procedure is called by 
\emph on
Write
\emph default
, if 
\emph on
Cleanup_On_Write
\emph default
 is set to Boolean 
\emph on
True
\emph default
.
 
\emph on
Cleanup_Size
\emph default
 is a sort of failsafe for this cache package.
 Since we can't know for sure what is being added (we don't know the keys
 beforehand), we need to make sure it doesn't gobble up all available resources.
 Set this number high enough that it'll never tricker under normal circumstances
, but low enough that it'll prevent resource exhaustion in case of errors.
\end_layout

\begin_layout Standard
The 
\emph on
Max_Element_Age
\emph default
 defaults to one hour.
 You should obviously set this to whatever suits your needs.
 This timer is used for all content in the cache.
 You cannot set this individually for each element.
\end_layout

\begin_layout Standard

\emph on
Reserved_Capacity
\emph default
 should be set as close as possible to the expected final size of the cache.
 If your best guestimate is 200 elements in the cache, then set this to
 200.
 Note that this setting has no bearing on the actual size of the cache.
 The cache will happily grow beyond the 
\emph on
Reserved_Capacity
\emph default
 value.
\end_layout

\begin_layout Subsection
Instantiation
\end_layout

\begin_layout Standard
Instantiating 
\emph on
String_Keys
\emph default
 is done like this:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

package My_Cache is new Yolk.Cache.String_Keys
\end_layout

\begin_layout Plain Layout

  (Element_Type      => Unbounded_String,
\end_layout

\begin_layout Plain Layout

   Reserved_Capacity => 200);
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
And that is all.
 We now have a 
\emph on
My_Cache
\emph default
 object that can hold objects of the type 
\emph on
Unbounded_String
\emph default
, all of which have a 
\emph on
Max_Element_Age
\emph default
 of 3600.0 seconds.
 Also we've told the cache to set aside at least 200 positions for content.
\end_layout

\begin_layout Subsection
Writing to the cache
\end_layout

\begin_layout Standard
Before we can read something from the cache, we must first write something
 to it:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

declare
\end_layout

\begin_layout Plain Layout

   Value : Unbounded_String := To_Unbounded_String ("42");
\end_layout

\begin_layout Plain Layout

begin
\end_layout

\begin_layout Plain Layout

   My_Cache.Write (Key   => "Foo",
\end_layout

\begin_layout Plain Layout

                   Value => Value);
\end_layout

\begin_layout Plain Layout

end;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Quotes eld
\end_inset

42
\begin_inset Quotes erd
\end_inset

 is now safely tucked away in the 
\emph on
My_Cache
\emph default
 object under the key 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset

, and will be so for 3600.0 seconds.
 Calling 
\emph on
Write
\emph default
 with the 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset


\emph on
 
\emph default
String will always overwrite earlier written 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset

 elements, no matter their age.
\end_layout

\begin_layout Subsection
Reading from the cache
\end_layout

\begin_layout Standard
A cache obviously only makes sense if you intend to read from it.
 In our case we want to get our hands on the previously written 
\begin_inset Quotes eld
\end_inset

Foo
\begin_inset Quotes erd
\end_inset

 value:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

declare
\end_layout

\begin_layout Plain Layout

   Valid : Boolean := False;
\end_layout

\begin_layout Plain Layout

   Value : Unbounded_String;
\end_layout

\begin_layout Plain Layout

begin
\end_layout

\begin_layout Plain Layout

   My_Cache.Read (Key      => "Foo",
\end_layout

\begin_layout Plain Layout

                  Is_Valid => Valid,
\end_layout

\begin_layout Plain Layout

                  Value    => Value);
\end_layout

\begin_layout Plain Layout

   if Valid then
\end_layout

\begin_layout Plain Layout

      --  do something interesting with the data
\end_layout

\begin_layout Plain Layout

   else
\end_layout

\begin_layout Plain Layout

      --  the Foo data is invalid.
\end_layout

\begin_layout Plain Layout

   end if;
\end_layout

\begin_layout Plain Layout

end;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
In order for an element to be valid (the
\emph on
 Is_Valid
\emph default
 parameter is true), it must:
\end_layout

\begin_layout Enumerate
have been added to the cache in the first place
\end_layout

\begin_layout Enumerate
be younger than 
\emph on
Max_Element_Age
\end_layout

\begin_layout Standard
If 
\emph on
Is_Valid
\emph default
 is 
\emph on
False
\emph default
, then 
\emph on
Value
\emph default
 contains undefined garbage.
 Note that if 
\emph on
Is_Valid
\emph default
 is 
\emph on
False
\emph default
 then 
\emph on
Key
\emph default
 is removed from the cache, if it exists.
\end_layout

\begin_layout Subsection
Checking if a key is valid
\end_layout

\begin_layout Standard
If you need to check whether a specific key exists in the cache and is valid,
 then you need to use the 
\emph on
Is_Valid
\emph default
 function.
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

if My_Cache.Is_Valid ("Foo") then
\end_layout

\begin_layout Plain Layout

   --  Foo is good!
\end_layout

\begin_layout Plain Layout

else
\end_layout

\begin_layout Plain Layout

   --  Foo is bad!
\end_layout

\begin_layout Plain Layout

end if;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
This follows the same rules as the 
\emph on
Is_Valid
\emph default
 parameter for the 
\emph on
Read
\emph default
 procedure.
\end_layout

\begin_layout Subsection
Clearing keys and the entire cache
\end_layout

\begin_layout Standard
For clearing of keys and the entire cache we have, naturally, two 
\emph on
Clear
\emph default
 procedures:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

-- First we clear the Foo key
\end_layout

\begin_layout Plain Layout

My_Cache.Clear (Key => "Foo");
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

--  And then we clear the entire cache
\end_layout

\begin_layout Plain Layout

My_Cache.Clear;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
How much is in there?
\end_layout

\begin_layout Standard
With the 
\emph on
Discrete_Keys
\emph default
 cache we obviously always know the exact amount of keys available, since
 we've defined the keys ourselves.
 This is not the case with the 
\emph on
String_Keys
\emph default
 cache, where any 
\emph on
String
\emph default
 can be a key.
 If we need to know how many elements that are currently in the cache, we
 call the 
\emph on
Length
\emph default
 function:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

if My_Cache.Length > 1000 then
\end_layout

\begin_layout Plain Layout

   --  Woa! Lots of stuff in the cache..
\end_layout

\begin_layout Plain Layout

end if;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that 
\emph on
Length
\emph default
 count both valid and invalid elements.
\end_layout

\begin_layout Subsection
Cleanup - Keeping cache size in check
\end_layout

\begin_layout Standard
if 
\emph on
Cleanup_On_Write
\emph default
 is 
\emph on
True
\emph default
, then 
\emph on
Cleanup
\emph default
 is called by 
\emph on
Write 
\emph default
whenever the size of the cache reach 
\emph on
Cleanup_Size
\emph default
.
 It is of course also possible to call it manually:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

if My_Cache.Length > 1000 then
\end_layout

\begin_layout Plain Layout

   My_Cache.Cleanup;
\end_layout

\begin_layout Plain Layout

end if;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you've set 
\emph on
Cleanup_On_Write
\emph default
 to Boolean 
\emph on
False
\emph default
 and the String keys are coming from outside sources, then you really should
 make sure you call 
\emph on
Cleanup
\emph default
 on a regular basis.
\end_layout

\begin_layout Section
Yolk.Command_Line
\end_layout

\begin_layout Standard
This package enables you to fetch the value of a given commandline parameter
 using the 
\emph on
Get
\emph default
 function:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

function Get       
\end_layout

\begin_layout Plain Layout

  (Parameter : in String;       
\end_layout

\begin_layout Plain Layout

   Default   : in String := "")        
\end_layout

\begin_layout Plain Layout

   return String;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If 
\emph on
Parameter
\emph default
 is found 
\emph on
Get
\emph default
 will return the value immediately following 
\emph on
Parameter.

\emph default
 If 
\emph on
Parameter
\emph default
 isn't found 
\emph on
Default
\emph default
 is returned.
 
\end_layout

\begin_layout Section
Yolk.Config_File_Parser
\end_layout

\begin_layout Standard
This package enables you to access KEY/VALUE pairs in configuration files
 that are written in the style:
\end_layout

\begin_layout LyX-Code
# This is a comment
\end_layout

\begin_layout LyX-Code
-- This is also a comment
\end_layout

\begin_layout LyX-Code
KEY VALUE
\end_layout

\begin_layout Standard
Keys are case-insensitive, so 
\emph on
FOO
\emph default
, 
\emph on
foo
\emph default
 and 
\emph on
fOo
\emph default
 are all the same.

\emph on
 
\emph default
Blank lines and comments are ignored and so is pre/postfixed whitespace.
 It is not necessary to quote values that contain whitespace, to this:
\end_layout

\begin_layout LyX-Code
KEY some value with whitespace
\end_layout

\begin_layout Standard
is perfectly valid, and will return 
\begin_inset Quotes eld
\end_inset


\emph on
some value with whitespace
\emph default

\begin_inset Quotes erd
\end_inset

 when calling 
\emph on
Get (KEY)
\emph default
.
 If VALUE is 
\emph on
Boolean
\emph default
 
\emph on
True
\emph default
 or 
\emph on
False
\emph default
 (case-insensitive), then the KEY can be returned as a 
\emph on
String
\emph default
 or a 
\emph on
Boolean
\emph default
, depending on the target type.
 If the target type does not match the VALUE and no sensible conversion
 can be made, then a 
\emph on
Conversion_Error
\emph default
 exception is raised.
 No dummy values are returned at any time.
\end_layout

\begin_layout Standard
To clear a default value, simply add the key to the configuration file,
 with no value set.
\end_layout

\begin_layout Subsection
The generic formal parameters
\end_layout

\begin_layout Standard
These are:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

generic
\end_layout

\begin_layout Plain Layout

   use Ada.Strings.Unbounded;
\end_layout

\begin_layout Plain Layout

   type Key_Type is (<>);
\end_layout

\begin_layout Plain Layout

   type Defaults_Array_Type is array (Key_Type) of Unbounded_String;
\end_layout

\begin_layout Plain Layout

   Defaults    : in Defaults_Array_Type;    
\end_layout

\begin_layout Plain Layout

   Config_File : in String;
\end_layout

\begin_layout Plain Layout

package Yolk.Config_File_Parser is
\end_layout

\begin_layout Plain Layout

...
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard

\emph on
Config_File
\emph default
 is of course the name and location of the configuration file.
\end_layout

\begin_layout Subsection
Exceptions
\end_layout

\begin_layout Standard
There are 3 different exceptions that can be raised by the 
\emph on
Yolk.Config_File_Parser
\emph default
 package.
 These are:
\end_layout

\begin_layout Itemize

\emph on
Unknown_Key
\emph default
.
 This is raised if an unknown key has been found in the configuration file
 given when instantiating the package or when 
\emph on
Load_File
\emph default
 is called.
\end_layout

\begin_layout Itemize

\emph on
Cannot_Open_Config_File
\emph default
.
 This is raised when 
\emph on
Config_File
\emph default
 cannot be read.
\end_layout

\begin_layout Itemize

\emph on
Conversion_Error
\emph default
.
 This is raised when a value cannot be converted to the target type, ie.
 the value 
\begin_inset Quotes eld
\end_inset

42
\begin_inset Quotes erd
\end_inset

 to a 
\emph on
Boolean
\emph default
.
\end_layout

\begin_layout Subsection
Instantiation
\end_layout

\begin_layout Standard

\emph on
Yolk.Config_File_Parser
\emph default
 is a generic package, so in order to use it, you have to instantiate it,
 like this:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

package My_Configuration is
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

   type Keys is (Foo, Bar);
\end_layout

\begin_layout Plain Layout

   type Defaults_Array is array (Keys) of Unbounded_String;
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

   Default_Values : constant Defaults_Array :=
\end_layout

\begin_layout Plain Layout

                      (Foo => To_Unbounded_String ("some foo"),
\end_layout

\begin_layout Plain Layout

                       Bar => To_Unbounded_String ("some bar"));
\end_layout

\begin_layout Plain Layout

   
\end_layout

\begin_layout Plain Layout

   package Config is new Yolk.Config_File_Parser
\end_layout

\begin_layout Plain Layout

     (Key_Type => Keys,
\end_layout

\begin_layout Plain Layout

      Defaults_Array_Type => Defaults_Array,
\end_layout

\begin_layout Plain Layout

      Defaults => Default_Value,
\end_layout

\begin_layout Plain Layout

      Config_File => "config.ini");
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

end My_Configuration;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Here we instantiate the 
\emph on
Config
\emph default
 package with 
\emph on
config.ini
\emph default
 as the configuration file.
 This means that KEY/VALUE pairs found in this file will overwrite the default
 values set in the 
\emph on
Default_Values
\emph default
 array.
 Setting a default value to 
\emph on
Null_Unbounded_String
\emph default
 means the value is empty.
\end_layout

\begin_layout Standard
Note that the 
\emph on
config.ini
\emph default
 file does not have to contain all the valid keys.
 It is perfectly fine to only add those keys that have non-default values
 to the configuration file.
\end_layout

\begin_layout Subsection
Re-loading configuration files
\end_layout

\begin_layout Standard
With the 
\emph on
Load_File
\emph default
 procedure you can re-load a new configuration file into your 
\emph on
Config
\emph default
 package:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

My_Configuration.Config.Load_File ("new_config.ini");
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now the KEY/VALUE pairs of 
\emph on
new_config.ini
\emph default
 will overwrite the ones originally found in the 
\emph on
config.ini
\emph default
 file the package was instantiated with.
 You can do this as many times as you like.
 Note that you cannot change what KEY's are valid, so if the 
\emph on
new_config.ini
\emph default
 file contains unknown keys, 
\emph on
Load_File
\emph default
 will raise the 
\emph on
Unknown_Key
\emph default
 exception.
\end_layout

\begin_layout Subsection
Getting values
\end_layout

\begin_layout Standard
With instantiation and loading of configuration files out of the way, it
 is now time to get to the configuration values.
 To get the value of the 
\emph on
Foo
\emph default
 key, you do:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

My_Configuration.Config.Get (Foo);
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
There are Get functions for the following types:
\end_layout

\begin_layout Itemize

\emph on
Boolean
\end_layout

\begin_layout Itemize

\emph on
Duration
\end_layout

\begin_layout Itemize

\emph on
Float
\end_layout

\begin_layout Itemize

\emph on
Integer
\end_layout

\begin_layout Itemize

\emph on
String
\end_layout

\begin_layout Itemize

\emph on
Unbounded_String
\end_layout

\begin_layout Standard
Empty keys simply return an empty 
\emph on
String
\emph default
 or a 
\emph on
Null_Unbounded_String
\emph default
, depending on the target type.
 If a key is empty and the target type is not a 
\emph on
String
\emph default
 or an 
\emph on
Unbounded_String
\emph default
, then the 
\emph on
Conversion_Error
\emph default
 exception is raised.
\end_layout

\begin_layout Subsection
Checking if a KEY has a VALUE
\end_layout

\begin_layout Standard
You can check if a key has a value with the 
\emph on
Has_Value
\emph default
 function:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

if Has_Value (Foo) then
\end_layout

\begin_layout Plain Layout

   Put_Line ("Foo has a value");
\end_layout

\begin_layout Plain Layout

end if;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Basically all this function does is return 
\emph on
Boolean
\emph default
 
\emph on
True
\emph default
 if the value of the given key is not a 
\emph on
Null_Unbounded_String
\emph default
.
\end_layout

\begin_layout Section
Yolk.Configuration
\end_layout

\begin_layout Standard
This package is a bit of an oddball, as all it does is instantiate the 
\emph on
Yolk.Config_File_Parser
\emph default
 generic with the default AWS and Yolk configuration values.
 This is used by Yolk internally, but also by the AWS component of your
 application.
 The instantiation looks like this:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

package Config is new Config_File_Parser
\end_layout

\begin_layout Plain Layout

  (Key_Type            => Keys,
\end_layout

\begin_layout Plain Layout

   Defaults_Array_Type => Defaults_Array,
\end_layout

\begin_layout Plain Layout

   Defaults            => Default_Values,
\end_layout

\begin_layout Plain Layout

   Config_File         => Config_File);
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
Config_File
\emph default
 function call return either the default Yolk configuration file (
\emph on
configuration/config.ini
\emph default
) or a user specified configuration file given by the 
\emph on
--yolk-config-file
\emph default
 command line argument, so
\emph on
 
\emph default
starting for example the Yolk demo like this:
\end_layout

\begin_layout LyX-Code
./yolk_demo --yolk-config-file /etc/yolk-config.ini
\end_layout

\begin_layout Standard
will force the demo to look for the 
\emph on
/etc/yolk-config.ini
\emph default
 configuration file.
\end_layout

\begin_layout Standard
There's a fully commented 
\emph on
config.ini.dist
\emph default
 file available in the 
\emph on
extras/
\emph default
 directory.
 I recommend taking a look at the Yolk demo application to see how the 
\emph on
Yolk.Configuration
\emph default
 package is used.
\end_layout

\begin_layout Subsection
Get the AWS specific configuration settings
\end_layout

\begin_layout Standard
On some occassions it might be necessary to get the AWS configuration object.
 This can easily be accomplished by calling the 
\emph on
Get_AWS_Configuration
\emph default
 function:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

AWS_Config : constant AWS.Config.Object := 
\end_layout

\begin_layout Plain Layout

  Yolk.Configuration.Get_AWS_Configuration;
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Yolk.Email
\end_layout

\begin_layout Standard
Using 
\emph on
Yolk.Email
\emph default
 and the child package 
\emph on
Yolk.Email.Composer
\emph default
 you can build and send more or less any kind of email:
\end_layout

\begin_layout Itemize
Plain text
\end_layout

\begin_layout Itemize
Multipart/Alternative
\end_layout

\begin_layout Itemize
Multipart/Mixed
\end_layout

\begin_layout Standard
The package supports adding multiple SMTP servers, meaning you can add as
 many as you need, and the email will then be send via the first one that
 accepts it.
\end_layout

\begin_layout Standard
The 
\emph on
Yolk.Email
\emph default
 package define 4 exceptions and 3 types.
 The facilities for actually constructing and sending the email are found
 in 
\emph on
Yolk.Email.Composer
\emph default
.
\end_layout

\begin_layout Subsection
Exceptions
\end_layout

\begin_layout Standard
These are:
\end_layout

\begin_layout Itemize

\emph on
Attachment_File_Not_Found
\emph default
.
 Is raised if a file attachment is not found at the given path.
\end_layout

\begin_layout Itemize

\emph on
No_Address_Set
\emph default
.
 Is raised if the address component of a To, Reply-To, From, Bcc/Cc header
 is missing.
\end_layout

\begin_layout Itemize

\emph on
No_Sender_Set_With_Multiple_From
\emph default
.
 Is raised when an email contains multiple From headers but no Sender header,
 as per RFC-5322, 3.6.2.
 http://tools.ietf.org/html/rfc5322
\end_layout

\begin_layout Itemize

\emph on
No_SMTP_Host_Set
\emph default
.
 Is raised if the SMTP host list is empty, ie.
 no SMTP host has been set for sending the email.
\end_layout

\begin_layout Subsection
The Yolk.Email types
\end_layout

\begin_layout Standard
When using 
\emph on
Yolk.Email.Composer
\emph default
 to build and send emails, three types declared in 
\emph on
Yolk.Email
\emph default
 are central:
\end_layout

\begin_layout Enumerate

\emph on
Character_Set
\end_layout

\begin_layout Enumerate

\emph on
Recipient_Kind
\end_layout

\begin_layout Enumerate

\emph on
Structure
\end_layout

\begin_layout Standard
The 
\emph on
Character_Set
\emph default
 type define what character set is used when data is added to an email 
\emph on
Structure
\emph default
 object.
 For example looking at the 
\emph on
Yolk.Email.Composer.Add_From
\emph default
 procedure, we see that the 
\emph on
Charset
\emph default
 parameter defaults to 
\emph on
US_ASCII
\emph default
:
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
inline false
status open

\begin_layout Plain Layout

procedure Add_From      
\end_layout

\begin_layout Plain Layout

  (ES        : in out Structure;       
\end_layout

\begin_layout Plain Layout

   Address   : in     String;       
\end_layout

\begin_layout Plain Layout

   Name      : in     String := "";       
\end_layout

\begin_layout Plain Layout

   Charset   : in     Character_Set := US_ASCII);
\end_layout

\end_inset


\end_layout

\end_ins…