PageRenderTime 136ms CodeModel.GetById 24ms app.highlight 98ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/yolk.lyx

http://github.com/ThomasLocke/yolk
Unknown | 7590 lines | 5787 code | 1803 blank | 0 comment | 0 complexity | 8005ac7db6ca7f09b6666c4d96179f72 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1#LyX 2.0 created this file. For more info see http://www.lyx.org/
   2\lyxformat 413
   3\begin_document
   4\begin_header
   5\textclass article
   6\use_default_options true
   7\maintain_unincluded_children false
   8\language english
   9\language_package default
  10\inputencoding auto
  11\fontencoding global
  12\font_roman default
  13\font_sans helvet
  14\font_typewriter default
  15\font_default_family sfdefault
  16\use_non_tex_fonts false
  17\font_sc false
  18\font_osf false
  19\font_sf_scale 100
  20\font_tt_scale 100
  21
  22\graphics default
  23\default_output_format default
  24\output_sync 0
  25\bibtex_command default
  26\index_command default
  27\paperfontsize 12
  28\spacing single
  29\use_hyperref false
  30\papersize a4paper
  31\use_geometry true
  32\use_amsmath 1
  33\use_esint 1
  34\use_mhchem 1
  35\use_mathdots 1
  36\cite_engine basic
  37\use_bibtopic false
  38\use_indices false
  39\paperorientation portrait
  40\suppress_date false
  41\use_refstyle 0
  42\index Index
  43\shortcut idx
  44\color #008000
  45\end_index
  46\leftmargin 2cm
  47\topmargin 2cm
  48\rightmargin 2cm
  49\bottommargin 2cm
  50\secnumdepth 3
  51\tocdepth 3
  52\paragraph_separation skip
  53\defskip medskip
  54\quotes_language english
  55\papercolumns 1
  56\papersides 1
  57\paperpagestyle default
  58\tracking_changes false
  59\output_changes false
  60\html_math_output 0
  61\html_css_as_file 0
  62\html_be_strict false
  63\end_header
  64
  65\begin_body
  66
  67\begin_layout Title
  68Yolk Manual
  69\end_layout
  70
  71\begin_layout Date
  72Revised December 11th.
  73 2012
  74\end_layout
  75
  76\begin_layout Standard
  77\begin_inset Newpage newpage
  78\end_inset
  79
  80
  81\end_layout
  82
  83\begin_layout Standard
  84\begin_inset CommandInset toc
  85LatexCommand tableofcontents
  86
  87\end_inset
  88
  89
  90\end_layout
  91
  92\begin_layout Standard
  93\begin_inset Newpage newpage
  94\end_inset
  95
  96
  97\end_layout
  98
  99\begin_layout Part
 100General Information
 101\end_layout
 102
 103\begin_layout Section
 104Copyright and License
 105\end_layout
 106
 107\begin_layout Standard
 108This document is copyright (C) 2010-, Thomas ¸cke.
 109 You may copy this document, in whole or in part, in any form or by any
 110 means, as is or with alterations, provided that (1) alterations are clearly
 111 marked as alterations and (2) this copyright notice is included unmodified
 112 in any copy.
 113\end_layout
 114
 115\begin_layout Standard
 116Yolk is GPLv3 software.
 117 You should have received a copy of the GNU General Public License and a
 118 copy of the GCC Runtime Library Exception along with this program; see
 119 the files COPYING3 and COPYING.RUNTIME respectively.
 120 If not, see 
 121\begin_inset CommandInset href
 122LatexCommand href
 123name "http://www.gnu.org/licenses/"
 124target "http://www.gnu.org/licenses/"
 125
 126\end_inset
 127
 128.
 129 
 130\end_layout
 131
 132\begin_layout Section
 133What is Yolk?
 134\end_layout
 135
 136\begin_layout Standard
 137Yolk is a collection of packages that aim to help build solid web-applications
 138 using Ada.
 139 Yolk itself doesn't do a whole lot that can't be accomplished simply by
 140 using 
 141\begin_inset CommandInset href
 142LatexCommand href
 143name "AWS"
 144target "http://libre.adacore.com/libre/tools/aws/"
 145
 146\end_inset
 147
 148 and the 
 149\begin_inset CommandInset href
 150LatexCommand href
 151name "GNAT Component Collection (GNATcoll)"
 152target "http://libre.adacore.com/libre/tools/gnat-component-collection/"
 153
 154\end_inset
 155
 156, but it does make the job of building complete web-applications a bit simpler.
 157 Things like changing user for the running application, catching POSIX signals
 158 such as SIGKILL, sending log data to syslogd, adding basic static content
 159 handlers, creating and starting/stopping an AWS powered HTTP server and
 160 building Atom syndication XML are all made a bit easier with Yolk.
 161\end_layout
 162
 163\begin_layout Standard
 164A Yolk application is in reality an AWS application, with some sugar added,
 165 so you're not really building a Yolk web-application, as much as you're
 166 building an AWS web-application.
 167 What I'm getting at, is that you need to understand how to use AWS, in
 168 order for Yolk to make any kind of sense.
 169 What you get when using Yolk is the little things that AWS does not readily
 170 provide.
 171\end_layout
 172
 173\begin_layout Subsection
 174The Yolk demo application
 175\end_layout
 176
 177\begin_layout Standard
 178Reading this manual will of course (I hope!) help you understand how to
 179 use Yolk, but please consider taking a closer look at the Yolk demo application
 180 to get a feel for how Yolk is actually used.
 181 The demo is heavily commented, so it should be fairly easy to understand
 182 what's going on.
 183 The demo application is also very suitable as a foundation for other AWS/Yolk
 184 applications.
 185\end_layout
 186
 187\begin_layout Standard
 188It is much easier to show how to use Yolk, than it is to write down all
 189 possible usage scenarios.
 190 With the combination of this manual, the Yolk source files and the demo
 191 application, you should be able to make full use of the Yolk packages in
 192 your own applications.
 193\end_layout
 194
 195\begin_layout Subsection
 196The source code
 197\end_layout
 198
 199\begin_layout Standard
 200The Yolk source code is the best documentation there is.
 201 This document is never going to be as comprehensive as the actual source,
 202 so I'll strongly suggest having the source code available as you read this
 203 document.
 204 What you will find in this document are short descriptions of what a package
 205 is meant to do and perhaps small usage examples, not a complete rundown
 206 of every type and procedure in a package.
 207\end_layout
 208
 209\begin_layout Subsection
 210Building and installing Yolk
 211\end_layout
 212
 213\begin_layout Standard
 214See the README and INSTALL files.
 215 These are found in the Yolk root directory.
 216\end_layout
 217
 218\begin_layout Subsection
 219The files Yolk depend upon
 220\end_layout
 221
 222\begin_layout Standard
 223When you read this document and the Yolk source code, you'll notice that
 224 quite a few packages depend on various files being available at specified
 225 locations.
 226 This is for example the case with the 
 227\emph on
 228Yolk.Whoops
 229\emph default
 230 package that expects its template file to be found at the path 
 231\emph on
 232templates/system/500.tmpl
 233\end_layout
 234
 235\begin_layout Standard
 236All such 
 237\begin_inset Quotes eld
 238\end_inset
 239
 240dependencies
 241\begin_inset Quotes erd
 242\end_inset
 243
 244 will of course be noted accordingly as we go along, but instead of forgetting
 245 one or more in your own application, I'd much rather encourage using the
 246 demo application as a foundation for your own applications, since all these
 247 fixed paths and files has been properly added to the demo.
 248\end_layout
 249
 250\begin_layout Standard
 251I also recommend compiling and running the demo, to make sure your Yolk
 252 install is working as intended.
 253 Just read the 
 254\emph on
 255demo/README
 256\emph default
 257 and 
 258\emph on
 259demo/INSTALL
 260\emph default
 261 files for instructions on how to get it up and running.
 262\end_layout
 263
 264\begin_layout Subsection
 265The Yolk packages naming
 266\end_layout
 267
 268\begin_layout Standard
 269The Yolk packages are pretty diverse, ranging from process control to sending
 270 email.
 271 I've tried naming them as sensibly as possible, in the hope that the package
 272 names alone give away their function.
 273 If I've failed, well, you're just going to have to refer to this document
 274 or take a look at the source for yourself.
 275\end_layout
 276
 277\begin_layout Standard
 278\begin_inset Newpage newpage
 279\end_inset
 280
 281
 282\end_layout
 283
 284\begin_layout Part
 285The Yolk Packages
 286\end_layout
 287
 288\begin_layout Section
 289Yolk
 290\end_layout
 291
 292\begin_layout Standard
 293The Yolk main package currently only contain only a few things: The Yolk
 294 
 295\emph on
 296Version
 297\emph default
 298 string, a 
 299\emph on
 300Config_File
 301\emph default
 302 function to get the location of the configuration file and a 
 303\emph on
 304PID_File
 305\emph default
 306 function to get the location of the PID file.
 307 These are used in a few places, for example in the 
 308\emph on
 309directory.tmpl
 310\emph default
 311 template file (the version string), in the 
 312\emph on
 313Yolk.Configuration
 314\emph default
 315 package (the 
 316\emph on
 317Config_File
 318\emph default
 319 function) and in the 
 320\emph on
 321Yolk.Process_Control
 322\emph default
 323 package (the 
 324\emph on
 325PID_File
 326\emph default
 327 function).
 328\end_layout
 329
 330\begin_layout Standard
 331All Yolk applications accepts two commandline arguments:
 332\end_layout
 333
 334\begin_layout Itemize
 335
 336\emph on
 337--yolk-config-file
 338\emph default
 339 : Defines the location of the configuration file.
 340 If empty or not set, then use the default location 
 341\emph on
 342configuration/config.ini
 343\emph default
 344.
 345\end_layout
 346
 347\begin_layout Itemize
 348
 349\emph on
 350--pid-file
 351\emph default
 352 : Defines the location of the PID file.
 353 If empty or not set, then don't write a PID file.
 354 Note that if you use the 
 355\emph on
 356extras/rc.yolk
 357\emph default
 358 script to control your application, then this is handled for you transparently.
 359\end_layout
 360
 361\begin_layout Section
 362Yolk.Cache.Discrete_Keys
 363\end_layout
 364
 365\begin_layout Standard
 366If a piece of data doesn't change very often and it is expensive to build,
 367 then caching it might be worthwhile.
 368 Instead of going to a file or database on every hit, you simply go to the
 369 cache and grab the latest version from there.
 370 This is 
 371\series bold
 372\emph on
 373very
 374\series default
 375\emph default
 376 fast, at the cost of some memory.
 377\end_layout
 378
 379\begin_layout Standard
 380If you know exactly what you want to cache, the 
 381\emph on
 382Yolk.Cache.Discrete_Keys
 383\emph default
 384 package might be just what you need.
 385\end_layout
 386
 387\begin_layout Subsection
 388The generic formal parameters
 389\end_layout
 390
 391\begin_layout Standard
 392These are:
 393\end_layout
 394
 395\begin_layout Standard
 396\begin_inset Box Frameless
 397position "t"
 398hor_pos "c"
 399has_inner_box 1
 400inner_pos "t"
 401use_parbox 0
 402use_makebox 0
 403width "100col%"
 404special "none"
 405height "1in"
 406height_special "totalheight"
 407status open
 408
 409\begin_layout Plain Layout
 410\begin_inset listings
 411lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 412inline false
 413status open
 414
 415\begin_layout Plain Layout
 416
 417generic
 418\end_layout
 419
 420\begin_layout Plain Layout
 421
 422   type Key_Type is (<>);
 423\end_layout
 424
 425\begin_layout Plain Layout
 426
 427   type Element_Type is private;
 428\end_layout
 429
 430\begin_layout Plain Layout
 431
 432   Max_Element_Age : Duration := 3600.0;
 433\end_layout
 434
 435\begin_layout Plain Layout
 436
 437package Yolk.Cache.Discrete_Keys is
 438\end_layout
 439
 440\begin_layout Plain Layout
 441
 442...
 443\end_layout
 444
 445\end_inset
 446
 447
 448\end_layout
 449
 450\end_inset
 451
 452
 453\end_layout
 454
 455\begin_layout Standard
 456The 
 457\emph on
 458Max_Element_Age
 459\emph default
 460 defaults to one hour.
 461 You should obviously set this to whatever suits your needs.
 462 This timer is used for all content in the cache.
 463 You cannot set this individually for each element.
 464\end_layout
 465
 466\begin_layout Subsection
 467Instantiation
 468\end_layout
 469
 470\begin_layout Standard
 471If for example we have two different sets of data (Foo and Bar) that are
 472 expensive to build, we can instantiate a 
 473\emph on
 474Discrete_Keys
 475\emph default
 476 package to handle this:
 477\end_layout
 478
 479\begin_layout Standard
 480\begin_inset Box Frameless
 481position "t"
 482hor_pos "c"
 483has_inner_box 1
 484inner_pos "t"
 485use_parbox 0
 486use_makebox 0
 487width "100col%"
 488special "none"
 489height "1in"
 490height_special "totalheight"
 491status open
 492
 493\begin_layout Plain Layout
 494\begin_inset listings
 495lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 496inline false
 497status open
 498
 499\begin_layout Plain Layout
 500
 501type Cache_Keys is (Foo, Bar);
 502\end_layout
 503
 504\begin_layout Plain Layout
 505
 506package My_Cache is new Yolk.Cache.Discrete_Keys
 507\end_layout
 508
 509\begin_layout Plain Layout
 510
 511  (Key_Type     => Cache_Keys,
 512\end_layout
 513
 514\begin_layout Plain Layout
 515
 516   Element_Type => Unbounded_String);
 517\end_layout
 518
 519\end_inset
 520
 521
 522\end_layout
 523
 524\end_inset
 525
 526
 527\end_layout
 528
 529\begin_layout Standard
 530And that is all.
 531 We now have a 
 532\emph on
 533My_Cache
 534\emph default
 535 object that can hold two objects: 
 536\emph on
 537Foo
 538\emph default
 539 and 
 540\emph on
 541Bar
 542\emph default
 543.
 544 These are of the type 
 545\emph on
 546Unbounded_String
 547\emph default
 548 and they have a 
 549\emph on
 550Max_Element_Age
 551\emph default
 552 of 3600.0 seconds.
 553\end_layout
 554
 555\begin_layout Subsection
 556Writing to the cache
 557\end_layout
 558
 559\begin_layout Standard
 560Before we can read something from the cache, we must first write something
 561 to it:
 562\end_layout
 563
 564\begin_layout Standard
 565\begin_inset Box Frameless
 566position "t"
 567hor_pos "c"
 568has_inner_box 1
 569inner_pos "t"
 570use_parbox 0
 571use_makebox 0
 572width "100col%"
 573special "none"
 574height "1in"
 575height_special "totalheight"
 576status open
 577
 578\begin_layout Plain Layout
 579\begin_inset listings
 580lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 581inline false
 582status open
 583
 584\begin_layout Plain Layout
 585
 586declare
 587\end_layout
 588
 589\begin_layout Plain Layout
 590
 591   Foo_Value : Unbounded_String := To_Unbounded_String ("Foo");
 592\end_layout
 593
 594\begin_layout Plain Layout
 595
 596begin
 597\end_layout
 598
 599\begin_layout Plain Layout
 600
 601   My_Cache.Write (Key   => Foo,
 602\end_layout
 603
 604\begin_layout Plain Layout
 605
 606                   Value => Foo_Value);
 607\end_layout
 608
 609\begin_layout Plain Layout
 610
 611end;
 612\end_layout
 613
 614\end_inset
 615
 616
 617\end_layout
 618
 619\end_inset
 620
 621
 622\end_layout
 623
 624\begin_layout Standard
 625That is all it takes: 
 626\begin_inset Quotes eld
 627\end_inset
 628
 629Foo
 630\begin_inset Quotes erd
 631\end_inset
 632
 633 is now safely tucked away in the 
 634\emph on
 635My_Cache
 636\emph default
 637 object, and will be so for 3600.0 seconds.
 638 Calling 
 639\emph on
 640Write
 641\emph default
 642 with the 
 643\emph on
 644Foo 
 645\emph default
 646key will always overwrite earlier written 
 647\emph on
 648Foo
 649\emph default
 650 elements, no matter their age.
 651\end_layout
 652
 653\begin_layout Subsection
 654Reading from the cache
 655\end_layout
 656
 657\begin_layout Standard
 658A cache obviously only makes sense if you intend to read from it.
 659 In our case we want to get our hands on the previously written 
 660\begin_inset Quotes eld
 661\end_inset
 662
 663Foo
 664\begin_inset Quotes erd
 665\end_inset
 666
 667 value:
 668\end_layout
 669
 670\begin_layout Standard
 671\begin_inset Box Frameless
 672position "t"
 673hor_pos "c"
 674has_inner_box 1
 675inner_pos "t"
 676use_parbox 0
 677use_makebox 0
 678width "100col%"
 679special "none"
 680height "1in"
 681height_special "totalheight"
 682status open
 683
 684\begin_layout Plain Layout
 685\begin_inset listings
 686lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 687inline false
 688status open
 689
 690\begin_layout Plain Layout
 691
 692declare
 693\end_layout
 694
 695\begin_layout Plain Layout
 696
 697   Valid : Boolean := False;
 698\end_layout
 699
 700\begin_layout Plain Layout
 701
 702   Value : Unbounded_String;
 703\end_layout
 704
 705\begin_layout Plain Layout
 706
 707begin
 708\end_layout
 709
 710\begin_layout Plain Layout
 711
 712   My_Cache.Read (Key      => Foo,
 713\end_layout
 714
 715\begin_layout Plain Layout
 716
 717                  Is_Valid => Valid,
 718\end_layout
 719
 720\begin_layout Plain Layout
 721
 722                  Value    => Value);
 723\end_layout
 724
 725\begin_layout Plain Layout
 726
 727   if Valid then
 728\end_layout
 729
 730\begin_layout Plain Layout
 731
 732      --  do something interesting with the data
 733\end_layout
 734
 735\begin_layout Plain Layout
 736
 737   else
 738\end_layout
 739
 740\begin_layout Plain Layout
 741
 742      --  the Foo data is invalid.
 743\end_layout
 744
 745\begin_layout Plain Layout
 746
 747   end if;
 748\end_layout
 749
 750\begin_layout Plain Layout
 751
 752end;
 753\end_layout
 754
 755\end_inset
 756
 757
 758\end_layout
 759
 760\end_inset
 761
 762
 763\end_layout
 764
 765\begin_layout Standard
 766In order for an element to be valid (the
 767\emph on
 768 Is_Valid
 769\emph default
 770 parameter is true), it must:
 771\end_layout
 772
 773\begin_layout Enumerate
 774have been added to the cache in the first place
 775\end_layout
 776
 777\begin_layout Enumerate
 778be younger than 
 779\emph on
 780Max_Element_Age
 781\end_layout
 782
 783\begin_layout Standard
 784If 
 785\emph on
 786Is_Valid
 787\emph default
 788 is 
 789\emph on
 790False
 791\emph default
 792, then 
 793\emph on
 794Value
 795\emph default
 796 is undefined.
 797 Note that if 
 798\emph on
 799Is_Valid
 800\emph default
 801 is 
 802\emph on
 803False
 804\emph default
 805 then 
 806\emph on
 807Key
 808\emph default
 809 is removed from the cache, if it exists.
 810\end_layout
 811
 812\begin_layout Subsection
 813Checking if a key is valid
 814\end_layout
 815
 816\begin_layout Standard
 817If you need to check whether a specific key exists in the cache and is valid,
 818 then you must use the 
 819\emph on
 820Is_Valid
 821\emph default
 822 function.
 823\end_layout
 824
 825\begin_layout Standard
 826\begin_inset Box Frameless
 827position "t"
 828hor_pos "c"
 829has_inner_box 1
 830inner_pos "t"
 831use_parbox 0
 832use_makebox 0
 833width "100col%"
 834special "none"
 835height "1in"
 836height_special "totalheight"
 837status open
 838
 839\begin_layout Plain Layout
 840\begin_inset listings
 841lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 842inline false
 843status open
 844
 845\begin_layout Plain Layout
 846
 847if My_Cache.Is_Valid (Foo) then
 848\end_layout
 849
 850\begin_layout Plain Layout
 851
 852   --  Foo is good!
 853\end_layout
 854
 855\begin_layout Plain Layout
 856
 857else
 858\end_layout
 859
 860\begin_layout Plain Layout
 861
 862   --  Foo is bad!
 863\end_layout
 864
 865\begin_layout Plain Layout
 866
 867end if;
 868\end_layout
 869
 870\end_inset
 871
 872
 873\end_layout
 874
 875\end_inset
 876
 877
 878\end_layout
 879
 880\begin_layout Standard
 881This follows the same rules as the 
 882\emph on
 883Is_Valid
 884\emph default
 885 parameter for the 
 886\emph on
 887Read
 888\emph default
 889 procedure.
 890\end_layout
 891
 892\begin_layout Subsection
 893Clearing keys and the entire cache
 894\end_layout
 895
 896\begin_layout Standard
 897For clearing of keys and the entire cache we have, naturally, two 
 898\emph on
 899Clear
 900\emph default
 901 procedures:
 902\end_layout
 903
 904\begin_layout Standard
 905\begin_inset Box Frameless
 906position "t"
 907hor_pos "c"
 908has_inner_box 1
 909inner_pos "t"
 910use_parbox 0
 911use_makebox 0
 912width "100col%"
 913special "none"
 914height "1in"
 915height_special "totalheight"
 916status open
 917
 918\begin_layout Plain Layout
 919\begin_inset listings
 920lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 921inline false
 922status open
 923
 924\begin_layout Plain Layout
 925
 926-- First we clear the Foo key
 927\end_layout
 928
 929\begin_layout Plain Layout
 930
 931My_Cache.Clear (Key => Foo);
 932\end_layout
 933
 934\begin_layout Plain Layout
 935
 936\end_layout
 937
 938\begin_layout Plain Layout
 939
 940--  And then we clear the entire cache
 941\end_layout
 942
 943\begin_layout Plain Layout
 944
 945My_Cache.Clear;
 946\end_layout
 947
 948\end_inset
 949
 950
 951\end_layout
 952
 953\end_inset
 954
 955
 956\end_layout
 957
 958\begin_layout Standard
 959And that's all it takes.
 960\end_layout
 961
 962\begin_layout Subsection
 963Cleanup - Getting rid of stale elements
 964\end_layout
 965
 966\begin_layout Standard
 967Calling Cleanup will delete all stale elements from the cache:
 968\end_layout
 969
 970\begin_layout Standard
 971\begin_inset Box Frameless
 972position "t"
 973hor_pos "c"
 974has_inner_box 1
 975inner_pos "t"
 976use_parbox 0
 977use_makebox 0
 978width "100col%"
 979special "none"
 980height "1in"
 981height_special "totalheight"
 982status open
 983
 984\begin_layout Plain Layout
 985\begin_inset listings
 986lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
 987inline false
 988status open
 989
 990\begin_layout Plain Layout
 991
 992My_Cache.Cleanup;
 993\end_layout
 994
 995\end_inset
 996
 997
 998\end_layout
 999
1000\end_inset
1001
1002
1003\end_layout
1004
1005\begin_layout Standard
1006Note that this is potentially a very expensive operation if the cache is
1007 large, as the entire cache is iterated and every element tested for its
1008 age.
1009 Use with care.
1010\end_layout
1011
1012\begin_layout Section
1013Yolk.Cache.String_Keys
1014\end_layout
1015
1016\begin_layout Standard
1017This package is almost similar to the 
1018\emph on
1019Yolk.Cache.Discrete_Keys
1020\emph default
1021 package.
1022 The biggest difference is that where the 
1023\emph on
1024Discrete_Keys
1025\emph default
1026 cache package requires that you define a type for the keys, this package
1027 use regular 
1028\emph on
1029String
1030\emph default
1031 as keys.
1032\end_layout
1033
1034\begin_layout Standard
1035The implications of this difference between the two cache packages are subtle.
1036 Both have the same 
1037\emph on
1038Read
1039\emph default
1040, 
1041\emph on
1042Write
1043\emph default
1044, 
1045\emph on
1046Is_Valid
1047\emph default
1048 and 
1049\emph on
1050Clear
1051\emph default
1052 procedures and functions, so in that sense the two packages are the same.
1053 The biggest difference lies in the available generic formal parameters
1054 and the functionality of the 
1055\emph on
1056Cleanup
1057\emph default
1058 procedure.
1059\end_layout
1060
1061\begin_layout Subsection
1062The generic formal parameters
1063\end_layout
1064
1065\begin_layout Standard
1066These are:
1067\end_layout
1068
1069\begin_layout Standard
1070\begin_inset Box Frameless
1071position "t"
1072hor_pos "c"
1073has_inner_box 1
1074inner_pos "t"
1075use_parbox 0
1076use_makebox 0
1077width "100col%"
1078special "none"
1079height "1in"
1080height_special "totalheight"
1081status open
1082
1083\begin_layout Plain Layout
1084\begin_inset listings
1085lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1086inline false
1087status open
1088
1089\begin_layout Plain Layout
1090
1091generic
1092\end_layout
1093
1094\begin_layout Plain Layout
1095
1096   type Element_Type is private;
1097\end_layout
1098
1099\begin_layout Plain Layout
1100
1101   Cleanup_Size      : Positive := 200;
1102\end_layout
1103
1104\begin_layout Plain Layout
1105
1106   Cleanup_On_Write  : Boolean  := True;
1107\end_layout
1108
1109\begin_layout Plain Layout
1110
1111   Max_Element_Age   : Duration := 3600.0;
1112\end_layout
1113
1114\begin_layout Plain Layout
1115
1116   Reserved_Capacity : Positive := 100;
1117\end_layout
1118
1119\begin_layout Plain Layout
1120
1121package Yolk.Cache.Discrete_Keys is
1122\end_layout
1123
1124\begin_layout Plain Layout
1125
1126...
1127\end_layout
1128
1129\end_inset
1130
1131
1132\end_layout
1133
1134\end_inset
1135
1136
1137\end_layout
1138
1139\begin_layout Standard
1140When the amount of elements in the cache >= 
1141\emph on
1142Cleanup_Size
1143\emph default
1144, then the 
1145\emph on
1146Cleanup
1147\emph default
1148 procedure is called by 
1149\emph on
1150Write
1151\emph default
1152, if 
1153\emph on
1154Cleanup_On_Write
1155\emph default
1156 is set to Boolean 
1157\emph on
1158True
1159\emph default
1160.
1161 
1162\emph on
1163Cleanup_Size
1164\emph default
1165 is a sort of failsafe for this cache package.
1166 Since we can't know for sure what is being added (we don't know the keys
1167 beforehand), we need to make sure it doesn't gobble up all available resources.
1168 Set this number high enough that it'll never tricker under normal circumstances
1169, but low enough that it'll prevent resource exhaustion in case of errors.
1170\end_layout
1171
1172\begin_layout Standard
1173The 
1174\emph on
1175Max_Element_Age
1176\emph default
1177 defaults to one hour.
1178 You should obviously set this to whatever suits your needs.
1179 This timer is used for all content in the cache.
1180 You cannot set this individually for each element.
1181\end_layout
1182
1183\begin_layout Standard
1184
1185\emph on
1186Reserved_Capacity
1187\emph default
1188 should be set as close as possible to the expected final size of the cache.
1189 If your best guestimate is 200 elements in the cache, then set this to
1190 200.
1191 Note that this setting has no bearing on the actual size of the cache.
1192 The cache will happily grow beyond the 
1193\emph on
1194Reserved_Capacity
1195\emph default
1196 value.
1197\end_layout
1198
1199\begin_layout Subsection
1200Instantiation
1201\end_layout
1202
1203\begin_layout Standard
1204Instantiating 
1205\emph on
1206String_Keys
1207\emph default
1208 is done like this:
1209\end_layout
1210
1211\begin_layout Standard
1212\begin_inset Box Frameless
1213position "t"
1214hor_pos "c"
1215has_inner_box 1
1216inner_pos "t"
1217use_parbox 0
1218use_makebox 0
1219width "100col%"
1220special "none"
1221height "1in"
1222height_special "totalheight"
1223status open
1224
1225\begin_layout Plain Layout
1226\begin_inset listings
1227lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1228inline false
1229status open
1230
1231\begin_layout Plain Layout
1232
1233package My_Cache is new Yolk.Cache.String_Keys
1234\end_layout
1235
1236\begin_layout Plain Layout
1237
1238  (Element_Type      => Unbounded_String,
1239\end_layout
1240
1241\begin_layout Plain Layout
1242
1243   Reserved_Capacity => 200);
1244\end_layout
1245
1246\end_inset
1247
1248
1249\end_layout
1250
1251\end_inset
1252
1253
1254\end_layout
1255
1256\begin_layout Standard
1257And that is all.
1258 We now have a 
1259\emph on
1260My_Cache
1261\emph default
1262 object that can hold objects of the type 
1263\emph on
1264Unbounded_String
1265\emph default
1266, all of which have a 
1267\emph on
1268Max_Element_Age
1269\emph default
1270 of 3600.0 seconds.
1271 Also we've told the cache to set aside at least 200 positions for content.
1272\end_layout
1273
1274\begin_layout Subsection
1275Writing to the cache
1276\end_layout
1277
1278\begin_layout Standard
1279Before we can read something from the cache, we must first write something
1280 to it:
1281\end_layout
1282
1283\begin_layout Standard
1284\begin_inset Box Frameless
1285position "t"
1286hor_pos "c"
1287has_inner_box 1
1288inner_pos "t"
1289use_parbox 0
1290use_makebox 0
1291width "100col%"
1292special "none"
1293height "1in"
1294height_special "totalheight"
1295status open
1296
1297\begin_layout Plain Layout
1298\begin_inset listings
1299lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1300inline false
1301status open
1302
1303\begin_layout Plain Layout
1304
1305declare
1306\end_layout
1307
1308\begin_layout Plain Layout
1309
1310   Value : Unbounded_String := To_Unbounded_String ("42");
1311\end_layout
1312
1313\begin_layout Plain Layout
1314
1315begin
1316\end_layout
1317
1318\begin_layout Plain Layout
1319
1320   My_Cache.Write (Key   => "Foo",
1321\end_layout
1322
1323\begin_layout Plain Layout
1324
1325                   Value => Value);
1326\end_layout
1327
1328\begin_layout Plain Layout
1329
1330end;
1331\end_layout
1332
1333\end_inset
1334
1335
1336\end_layout
1337
1338\end_inset
1339
1340
1341\end_layout
1342
1343\begin_layout Standard
1344\begin_inset Quotes eld
1345\end_inset
1346
134742
1348\begin_inset Quotes erd
1349\end_inset
1350
1351 is now safely tucked away in the 
1352\emph on
1353My_Cache
1354\emph default
1355 object under the key 
1356\begin_inset Quotes eld
1357\end_inset
1358
1359Foo
1360\begin_inset Quotes erd
1361\end_inset
1362
1363, and will be so for 3600.0 seconds.
1364 Calling 
1365\emph on
1366Write
1367\emph default
1368 with the 
1369\begin_inset Quotes eld
1370\end_inset
1371
1372Foo
1373\begin_inset Quotes erd
1374\end_inset
1375
1376
1377\emph on
1378 
1379\emph default
1380String will always overwrite earlier written 
1381\begin_inset Quotes eld
1382\end_inset
1383
1384Foo
1385\begin_inset Quotes erd
1386\end_inset
1387
1388 elements, no matter their age.
1389\end_layout
1390
1391\begin_layout Subsection
1392Reading from the cache
1393\end_layout
1394
1395\begin_layout Standard
1396A cache obviously only makes sense if you intend to read from it.
1397 In our case we want to get our hands on the previously written 
1398\begin_inset Quotes eld
1399\end_inset
1400
1401Foo
1402\begin_inset Quotes erd
1403\end_inset
1404
1405 value:
1406\end_layout
1407
1408\begin_layout Standard
1409\begin_inset Box Frameless
1410position "t"
1411hor_pos "c"
1412has_inner_box 1
1413inner_pos "t"
1414use_parbox 0
1415use_makebox 0
1416width "100col%"
1417special "none"
1418height "1in"
1419height_special "totalheight"
1420status open
1421
1422\begin_layout Plain Layout
1423\begin_inset listings
1424lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1425inline false
1426status open
1427
1428\begin_layout Plain Layout
1429
1430declare
1431\end_layout
1432
1433\begin_layout Plain Layout
1434
1435   Valid : Boolean := False;
1436\end_layout
1437
1438\begin_layout Plain Layout
1439
1440   Value : Unbounded_String;
1441\end_layout
1442
1443\begin_layout Plain Layout
1444
1445begin
1446\end_layout
1447
1448\begin_layout Plain Layout
1449
1450   My_Cache.Read (Key      => "Foo",
1451\end_layout
1452
1453\begin_layout Plain Layout
1454
1455                  Is_Valid => Valid,
1456\end_layout
1457
1458\begin_layout Plain Layout
1459
1460                  Value    => Value);
1461\end_layout
1462
1463\begin_layout Plain Layout
1464
1465   if Valid then
1466\end_layout
1467
1468\begin_layout Plain Layout
1469
1470      --  do something interesting with the data
1471\end_layout
1472
1473\begin_layout Plain Layout
1474
1475   else
1476\end_layout
1477
1478\begin_layout Plain Layout
1479
1480      --  the Foo data is invalid.
1481\end_layout
1482
1483\begin_layout Plain Layout
1484
1485   end if;
1486\end_layout
1487
1488\begin_layout Plain Layout
1489
1490end;
1491\end_layout
1492
1493\end_inset
1494
1495
1496\end_layout
1497
1498\end_inset
1499
1500
1501\end_layout
1502
1503\begin_layout Standard
1504In order for an element to be valid (the
1505\emph on
1506 Is_Valid
1507\emph default
1508 parameter is true), it must:
1509\end_layout
1510
1511\begin_layout Enumerate
1512have been added to the cache in the first place
1513\end_layout
1514
1515\begin_layout Enumerate
1516be younger than 
1517\emph on
1518Max_Element_Age
1519\end_layout
1520
1521\begin_layout Standard
1522If 
1523\emph on
1524Is_Valid
1525\emph default
1526 is 
1527\emph on
1528False
1529\emph default
1530, then 
1531\emph on
1532Value
1533\emph default
1534 contains undefined garbage.
1535 Note that if 
1536\emph on
1537Is_Valid
1538\emph default
1539 is 
1540\emph on
1541False
1542\emph default
1543 then 
1544\emph on
1545Key
1546\emph default
1547 is removed from the cache, if it exists.
1548\end_layout
1549
1550\begin_layout Subsection
1551Checking if a key is valid
1552\end_layout
1553
1554\begin_layout Standard
1555If you need to check whether a specific key exists in the cache and is valid,
1556 then you need to use the 
1557\emph on
1558Is_Valid
1559\emph default
1560 function.
1561\end_layout
1562
1563\begin_layout Standard
1564\begin_inset Box Frameless
1565position "t"
1566hor_pos "c"
1567has_inner_box 1
1568inner_pos "t"
1569use_parbox 0
1570use_makebox 0
1571width "100col%"
1572special "none"
1573height "1in"
1574height_special "totalheight"
1575status open
1576
1577\begin_layout Plain Layout
1578\begin_inset listings
1579lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1580inline false
1581status open
1582
1583\begin_layout Plain Layout
1584
1585if My_Cache.Is_Valid ("Foo") then
1586\end_layout
1587
1588\begin_layout Plain Layout
1589
1590   --  Foo is good!
1591\end_layout
1592
1593\begin_layout Plain Layout
1594
1595else
1596\end_layout
1597
1598\begin_layout Plain Layout
1599
1600   --  Foo is bad!
1601\end_layout
1602
1603\begin_layout Plain Layout
1604
1605end if;
1606\end_layout
1607
1608\end_inset
1609
1610
1611\end_layout
1612
1613\end_inset
1614
1615
1616\end_layout
1617
1618\begin_layout Standard
1619This follows the same rules as the 
1620\emph on
1621Is_Valid
1622\emph default
1623 parameter for the 
1624\emph on
1625Read
1626\emph default
1627 procedure.
1628\end_layout
1629
1630\begin_layout Subsection
1631Clearing keys and the entire cache
1632\end_layout
1633
1634\begin_layout Standard
1635For clearing of keys and the entire cache we have, naturally, two 
1636\emph on
1637Clear
1638\emph default
1639 procedures:
1640\end_layout
1641
1642\begin_layout Standard
1643\begin_inset Box Frameless
1644position "t"
1645hor_pos "c"
1646has_inner_box 1
1647inner_pos "t"
1648use_parbox 0
1649use_makebox 0
1650width "100col%"
1651special "none"
1652height "1in"
1653height_special "totalheight"
1654status open
1655
1656\begin_layout Plain Layout
1657\begin_inset listings
1658lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1659inline false
1660status open
1661
1662\begin_layout Plain Layout
1663
1664-- First we clear the Foo key
1665\end_layout
1666
1667\begin_layout Plain Layout
1668
1669My_Cache.Clear (Key => "Foo");
1670\end_layout
1671
1672\begin_layout Plain Layout
1673
1674\end_layout
1675
1676\begin_layout Plain Layout
1677
1678--  And then we clear the entire cache
1679\end_layout
1680
1681\begin_layout Plain Layout
1682
1683My_Cache.Clear;
1684\end_layout
1685
1686\end_inset
1687
1688
1689\end_layout
1690
1691\end_inset
1692
1693
1694\end_layout
1695
1696\begin_layout Subsection
1697How much is in there?
1698\end_layout
1699
1700\begin_layout Standard
1701With the 
1702\emph on
1703Discrete_Keys
1704\emph default
1705 cache we obviously always know the exact amount of keys available, since
1706 we've defined the keys ourselves.
1707 This is not the case with the 
1708\emph on
1709String_Keys
1710\emph default
1711 cache, where any 
1712\emph on
1713String
1714\emph default
1715 can be a key.
1716 If we need to know how many elements that are currently in the cache, we
1717 call the 
1718\emph on
1719Length
1720\emph default
1721 function:
1722\end_layout
1723
1724\begin_layout Standard
1725\begin_inset Box Frameless
1726position "t"
1727hor_pos "c"
1728has_inner_box 1
1729inner_pos "t"
1730use_parbox 0
1731use_makebox 0
1732width "100col%"
1733special "none"
1734height "1in"
1735height_special "totalheight"
1736status open
1737
1738\begin_layout Plain Layout
1739\begin_inset listings
1740lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1741inline false
1742status open
1743
1744\begin_layout Plain Layout
1745
1746if My_Cache.Length > 1000 then
1747\end_layout
1748
1749\begin_layout Plain Layout
1750
1751   --  Woa! Lots of stuff in the cache..
1752\end_layout
1753
1754\begin_layout Plain Layout
1755
1756end if;
1757\end_layout
1758
1759\end_inset
1760
1761
1762\end_layout
1763
1764\end_inset
1765
1766
1767\end_layout
1768
1769\begin_layout Standard
1770Note that 
1771\emph on
1772Length
1773\emph default
1774 count both valid and invalid elements.
1775\end_layout
1776
1777\begin_layout Subsection
1778Cleanup - Keeping cache size in check
1779\end_layout
1780
1781\begin_layout Standard
1782if 
1783\emph on
1784Cleanup_On_Write
1785\emph default
1786 is 
1787\emph on
1788True
1789\emph default
1790, then 
1791\emph on
1792Cleanup
1793\emph default
1794 is called by 
1795\emph on
1796Write 
1797\emph default
1798whenever the size of the cache reach 
1799\emph on
1800Cleanup_Size
1801\emph default
1802.
1803 It is of course also possible to call it manually:
1804\end_layout
1805
1806\begin_layout Standard
1807\begin_inset Box Frameless
1808position "t"
1809hor_pos "c"
1810has_inner_box 1
1811inner_pos "t"
1812use_parbox 0
1813use_makebox 0
1814width "100col%"
1815special "none"
1816height "1in"
1817height_special "totalheight"
1818status open
1819
1820\begin_layout Plain Layout
1821\begin_inset listings
1822lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1823inline false
1824status open
1825
1826\begin_layout Plain Layout
1827
1828if My_Cache.Length > 1000 then
1829\end_layout
1830
1831\begin_layout Plain Layout
1832
1833   My_Cache.Cleanup;
1834\end_layout
1835
1836\begin_layout Plain Layout
1837
1838end if;
1839\end_layout
1840
1841\end_inset
1842
1843
1844\end_layout
1845
1846\end_inset
1847
1848
1849\end_layout
1850
1851\begin_layout Standard
1852If you've set 
1853\emph on
1854Cleanup_On_Write
1855\emph default
1856 to Boolean 
1857\emph on
1858False
1859\emph default
1860 and the String keys are coming from outside sources, then you really should
1861 make sure you call 
1862\emph on
1863Cleanup
1864\emph default
1865 on a regular basis.
1866\end_layout
1867
1868\begin_layout Section
1869Yolk.Command_Line
1870\end_layout
1871
1872\begin_layout Standard
1873This package enables you to fetch the value of a given commandline parameter
1874 using the 
1875\emph on
1876Get
1877\emph default
1878 function:
1879\end_layout
1880
1881\begin_layout Standard
1882\begin_inset Box Frameless
1883position "t"
1884hor_pos "c"
1885has_inner_box 1
1886inner_pos "t"
1887use_parbox 0
1888use_makebox 0
1889width "100col%"
1890special "none"
1891height "1in"
1892height_special "totalheight"
1893status open
1894
1895\begin_layout Plain Layout
1896\begin_inset listings
1897lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
1898inline false
1899status open
1900
1901\begin_layout Plain Layout
1902
1903function Get       
1904\end_layout
1905
1906\begin_layout Plain Layout
1907
1908  (Parameter : in String;       
1909\end_layout
1910
1911\begin_layout Plain Layout
1912
1913   Default   : in String := "")        
1914\end_layout
1915
1916\begin_layout Plain Layout
1917
1918   return String;
1919\end_layout
1920
1921\end_inset
1922
1923
1924\end_layout
1925
1926\end_inset
1927
1928
1929\end_layout
1930
1931\begin_layout Standard
1932If 
1933\emph on
1934Parameter
1935\emph default
1936 is found 
1937\emph on
1938Get
1939\emph default
1940 will return the value immediately following 
1941\emph on
1942Parameter.
1943
1944\emph default
1945 If 
1946\emph on
1947Parameter
1948\emph default
1949 isn't found 
1950\emph on
1951Default
1952\emph default
1953 is returned.
1954 
1955\end_layout
1956
1957\begin_layout Section
1958Yolk.Config_File_Parser
1959\end_layout
1960
1961\begin_layout Standard
1962This package enables you to access KEY/VALUE pairs in configuration files
1963 that are written in the style:
1964\end_layout
1965
1966\begin_layout LyX-Code
1967# This is a comment
1968\end_layout
1969
1970\begin_layout LyX-Code
1971-- This is also a comment
1972\end_layout
1973
1974\begin_layout LyX-Code
1975KEY VALUE
1976\end_layout
1977
1978\begin_layout Standard
1979Keys are case-insensitive, so 
1980\emph on
1981FOO
1982\emph default
1983, 
1984\emph on
1985foo
1986\emph default
1987 and 
1988\emph on
1989fOo
1990\emph default
1991 are all the same.
1992
1993\emph on
1994 
1995\emph default
1996Blank lines and comments are ignored and so is pre/postfixed whitespace.
1997 It is not necessary to quote values that contain whitespace, to this:
1998\end_layout
1999
2000\begin_layout LyX-Code
2001KEY some value with whitespace
2002\end_layout
2003
2004\begin_layout Standard
2005is perfectly valid, and will return 
2006\begin_inset Quotes eld
2007\end_inset
2008
2009
2010\emph on
2011some value with whitespace
2012\emph default
2013
2014\begin_inset Quotes erd
2015\end_inset
2016
2017 when calling 
2018\emph on
2019Get (KEY)
2020\emph default
2021.
2022 If VALUE is 
2023\emph on
2024Boolean
2025\emph default
2026 
2027\emph on
2028True
2029\emph default
2030 or 
2031\emph on
2032False
2033\emph default
2034 (case-insensitive), then the KEY can be returned as a 
2035\emph on
2036String
2037\emph default
2038 or a 
2039\emph on
2040Boolean
2041\emph default
2042, depending on the target type.
2043 If the target type does not match the VALUE and no sensible conversion
2044 can be made, then a 
2045\emph on
2046Conversion_Error
2047\emph default
2048 exception is raised.
2049 No dummy values are returned at any time.
2050\end_layout
2051
2052\begin_layout Standard
2053To clear a default value, simply add the key to the configuration file,
2054 with no value set.
2055\end_layout
2056
2057\begin_layout Subsection
2058The generic formal parameters
2059\end_layout
2060
2061\begin_layout Standard
2062These are:
2063\end_layout
2064
2065\begin_layout Standard
2066\begin_inset Box Frameless
2067position "t"
2068hor_pos "c"
2069has_inner_box 1
2070inner_pos "t"
2071use_parbox 0
2072use_makebox 0
2073width "100col%"
2074special "none"
2075height "1in"
2076height_special "totalheight"
2077status open
2078
2079\begin_layout Plain Layout
2080\begin_inset listings
2081lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2082inline false
2083status open
2084
2085\begin_layout Plain Layout
2086
2087generic
2088\end_layout
2089
2090\begin_layout Plain Layout
2091
2092   use Ada.Strings.Unbounded;
2093\end_layout
2094
2095\begin_layout Plain Layout
2096
2097   type Key_Type is (<>);
2098\end_layout
2099
2100\begin_layout Plain Layout
2101
2102   type Defaults_Array_Type is array (Key_Type) of Unbounded_String;
2103\end_layout
2104
2105\begin_layout Plain Layout
2106
2107   Defaults    : in Defaults_Array_Type;    
2108\end_layout
2109
2110\begin_layout Plain Layout
2111
2112   Config_File : in String;
2113\end_layout
2114
2115\begin_layout Plain Layout
2116
2117package Yolk.Config_File_Parser is
2118\end_layout
2119
2120\begin_layout Plain Layout
2121
2122...
2123\end_layout
2124
2125\end_inset
2126
2127
2128\end_layout
2129
2130\end_inset
2131
2132
2133\end_layout
2134
2135\begin_layout Standard
2136
2137\emph on
2138Config_File
2139\emph default
2140 is of course the name and location of the configuration file.
2141\end_layout
2142
2143\begin_layout Subsection
2144Exceptions
2145\end_layout
2146
2147\begin_layout Standard
2148There are 3 different exceptions that can be raised by the 
2149\emph on
2150Yolk.Config_File_Parser
2151\emph default
2152 package.
2153 These are:
2154\end_layout
2155
2156\begin_layout Itemize
2157
2158\emph on
2159Unknown_Key
2160\emph default
2161.
2162 This is raised if an unknown key has been found in the configuration file
2163 given when instantiating the package or when 
2164\emph on
2165Load_File
2166\emph default
2167 is called.
2168\end_layout
2169
2170\begin_layout Itemize
2171
2172\emph on
2173Cannot_Open_Config_File
2174\emph default
2175.
2176 This is raised when 
2177\emph on
2178Config_File
2179\emph default
2180 cannot be read.
2181\end_layout
2182
2183\begin_layout Itemize
2184
2185\emph on
2186Conversion_Error
2187\emph default
2188.
2189 This is raised when a value cannot be converted to the target type, ie.
2190 the value 
2191\begin_inset Quotes eld
2192\end_inset
2193
219442
2195\begin_inset Quotes erd
2196\end_inset
2197
2198 to a 
2199\emph on
2200Boolean
2201\emph default
2202.
2203\end_layout
2204
2205\begin_layout Subsection
2206Instantiation
2207\end_layout
2208
2209\begin_layout Standard
2210
2211\emph on
2212Yolk.Config_File_Parser
2213\emph default
2214 is a generic package, so in order to use it, you have to instantiate it,
2215 like this:
2216\end_layout
2217
2218\begin_layout Standard
2219\begin_inset Box Frameless
2220position "t"
2221hor_pos "c"
2222has_inner_box 1
2223inner_pos "t"
2224use_parbox 0
2225use_makebox 0
2226width "100col%"
2227special "none"
2228height "1in"
2229height_special "totalheight"
2230status open
2231
2232\begin_layout Plain Layout
2233\begin_inset listings
2234lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2235inline false
2236status open
2237
2238\begin_layout Plain Layout
2239
2240package My_Configuration is
2241\end_layout
2242
2243\begin_layout Plain Layout
2244
2245\end_layout
2246
2247\begin_layout Plain Layout
2248
2249   type Keys is (Foo, Bar);
2250\end_layout
2251
2252\begin_layout Plain Layout
2253
2254   type Defaults_Array is array (Keys) of Unbounded_String;
2255\end_layout
2256
2257\begin_layout Plain Layout
2258
2259\end_layout
2260
2261\begin_layout Plain Layout
2262
2263   Default_Values : constant Defaults_Array :=
2264\end_layout
2265
2266\begin_layout Plain Layout
2267
2268                      (Foo => To_Unbounded_String ("some foo"),
2269\end_layout
2270
2271\begin_layout Plain Layout
2272
2273                       Bar => To_Unbounded_String ("some bar"));
2274\end_layout
2275
2276\begin_layout Plain Layout
2277
2278   
2279\end_layout
2280
2281\begin_layout Plain Layout
2282
2283   package Config is new Yolk.Config_File_Parser
2284\end_layout
2285
2286\begin_layout Plain Layout
2287
2288     (Key_Type => Keys,
2289\end_layout
2290
2291\begin_layout Plain Layout
2292
2293      Defaults_Array_Type => Defaults_Array,
2294\end_layout
2295
2296\begin_layout Plain Layout
2297
2298      Defaults => Default_Value,
2299\end_layout
2300
2301\begin_layout Plain Layout
2302
2303      Config_File => "config.ini");
2304\end_layout
2305
2306\begin_layout Plain Layout
2307
2308\end_layout
2309
2310\begin_layout Plain Layout
2311
2312end My_Configuration;
2313\end_layout
2314
2315\end_inset
2316
2317
2318\end_layout
2319
2320\end_inset
2321
2322
2323\end_layout
2324
2325\begin_layout Standard
2326Here we instantiate the 
2327\emph on
2328Config
2329\emph default
2330 package with 
2331\emph on
2332config.ini
2333\emph default
2334 as the configuration file.
2335 This means that KEY/VALUE pairs found in this file will overwrite the default
2336 values set in the 
2337\emph on
2338Default_Values
2339\emph default
2340 array.
2341 Setting a default value to 
2342\emph on
2343Null_Unbounded_String
2344\emph default
2345 means the value is empty.
2346\end_layout
2347
2348\begin_layout Standard
2349Note that the 
2350\emph on
2351config.ini
2352\emph default
2353 file does not have to contain all the valid keys.
2354 It is perfectly fine to only add those keys that have non-default values
2355 to the configuration file.
2356\end_layout
2357
2358\begin_layout Subsection
2359Re-loading configuration files
2360\end_layout
2361
2362\begin_layout Standard
2363With the 
2364\emph on
2365Load_File
2366\emph default
2367 procedure you can re-load a new configuration file into your 
2368\emph on
2369Config
2370\emph default
2371 package:
2372\end_layout
2373
2374\begin_layout Standard
2375\begin_inset Box Frameless
2376position "t"
2377hor_pos "c"
2378has_inner_box 1
2379inner_pos "t"
2380use_parbox 0
2381use_makebox 0
2382width "100col%"
2383special "none"
2384height "1in"
2385height_special "totalheight"
2386status open
2387
2388\begin_layout Plain Layout
2389\begin_inset listings
2390lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2391inline false
2392status open
2393
2394\begin_layout Plain Layout
2395
2396My_Configuration.Config.Load_File ("new_config.ini");
2397\end_layout
2398
2399\end_inset
2400
2401
2402\end_layout
2403
2404\end_inset
2405
2406
2407\end_layout
2408
2409\begin_layout Standard
2410Now the KEY/VALUE pairs of 
2411\emph on
2412new_config.ini
2413\emph default
2414 will overwrite the ones originally found in the 
2415\emph on
2416config.ini
2417\emph default
2418 file the package was instantiated with.
2419 You can do this as many times as you like.
2420 Note that you cannot change what KEY's are valid, so if the 
2421\emph on
2422new_config.ini
2423\emph default
2424 file contains unknown keys, 
2425\emph on
2426Load_File
2427\emph default
2428 will raise the 
2429\emph on
2430Unknown_Key
2431\emph default
2432 exception.
2433\end_layout
2434
2435\begin_layout Subsection
2436Getting values
2437\end_layout
2438
2439\begin_layout Standard
2440With instantiation and loading of configuration files out of the way, it
2441 is now time to get to the configuration values.
2442 To get the value of the 
2443\emph on
2444Foo
2445\emph default
2446 key, you do:
2447\end_layout
2448
2449\begin_layout Standard
2450\begin_inset Box Frameless
2451position "t"
2452hor_pos "c"
2453has_inner_box 1
2454inner_pos "t"
2455use_parbox 0
2456use_makebox 0
2457width "100col%"
2458special "none"
2459height "1in"
2460height_special "totalheight"
2461status open
2462
2463\begin_layout Plain Layout
2464\begin_inset listings
2465lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2466inline false
2467status open
2468
2469\begin_layout Plain Layout
2470
2471My_Configuration.Config.Get (Foo);
2472\end_layout
2473
2474\end_inset
2475
2476
2477\end_layout
2478
2479\end_inset
2480
2481
2482\end_layout
2483
2484\begin_layout Standard
2485There are Get functions for the following types:
2486\end_layout
2487
2488\begin_layout Itemize
2489
2490\emph on
2491Boolean
2492\end_layout
2493
2494\begin_layout Itemize
2495
2496\emph on
2497Duration
2498\end_layout
2499
2500\begin_layout Itemize
2501
2502\emph on
2503Float
2504\end_layout
2505
2506\begin_layout Itemize
2507
2508\emph on
2509Integer
2510\end_layout
2511
2512\begin_layout Itemize
2513
2514\emph on
2515String
2516\end_layout
2517
2518\begin_layout Itemize
2519
2520\emph on
2521Unbounded_String
2522\end_layout
2523
2524\begin_layout Standard
2525Empty keys simply return an empty 
2526\emph on
2527String
2528\emph default
2529 or a 
2530\emph on
2531Null_Unbounded_String
2532\emph default
2533, depending on the target type.
2534 If a key is empty and the target type is not a 
2535\emph on
2536String
2537\emph default
2538 or an 
2539\emph on
2540Unbounded_String
2541\emph default
2542, then the 
2543\emph on
2544Conversion_Error
2545\emph default
2546 exception is raised.
2547\end_layout
2548
2549\begin_layout Subsection
2550Checking if a KEY has a VALUE
2551\end_layout
2552
2553\begin_layout Standard
2554You can check if a key has a value with the 
2555\emph on
2556Has_Value
2557\emph default
2558 function:
2559\end_layout
2560
2561\begin_layout Standard
2562\begin_inset Box Frameless
2563position "t"
2564hor_pos "c"
2565has_inner_box 1
2566inner_pos "t"
2567use_parbox 0
2568use_makebox 0
2569width "100col%"
2570special "none"
2571height "1in"
2572height_special "totalheight"
2573status open
2574
2575\begin_layout Plain Layout
2576\begin_inset listings
2577lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2578inline false
2579status open
2580
2581\begin_layout Plain Layout
2582
2583if Has_Value (Foo) then
2584\end_layout
2585
2586\begin_layout Plain Layout
2587
2588   Put_Line ("Foo has a value");
2589\end_layout
2590
2591\begin_layout Plain Layout
2592
2593end if;
2594\end_layout
2595
2596\end_inset
2597
2598
2599\end_layout
2600
2601\end_inset
2602
2603
2604\end_layout
2605
2606\begin_layout Standard
2607Basically all this function does is return 
2608\emph on
2609Boolean
2610\emph default
2611 
2612\emph on
2613True
2614\emph default
2615 if the value of the given key is not a 
2616\emph on
2617Null_Unbounded_String
2618\emph default
2619.
2620\end_layout
2621
2622\begin_layout Section
2623Yolk.Configuration
2624\end_layout
2625
2626\begin_layout Standard
2627This package is a bit of an oddball, as all it does is instantiate the 
2628\emph on
2629Yolk.Config_File_Parser
2630\emph default
2631 generic with the default AWS and Yolk configuration values.
2632 This is used by Yolk internally, but also by the AWS component of your
2633 application.
2634 The instantiation looks like this:
2635\end_layout
2636
2637\begin_layout Standard
2638\begin_inset Box Frameless
2639position "t"
2640hor_pos "c"
2641has_inner_box 1
2642inner_pos "t"
2643use_parbox 0
2644use_makebox 0
2645width "100col%"
2646special "none"
2647height "1in"
2648height_special "totalheight"
2649status open
2650
2651\begin_layout Plain Layout
2652\begin_inset listings
2653lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2654inline false
2655status open
2656
2657\begin_layout Plain Layout
2658
2659package Config is new Config_File_Parser
2660\end_layout
2661
2662\begin_layout Plain Layout
2663
2664  (Key_Type            => Keys,
2665\end_layout
2666
2667\begin_layout Plain Layout
2668
2669   Defaults_Array_Type => Defaults_Array,
2670\end_layout
2671
2672\begin_layout Plain Layout
2673
2674   Defaults            => Default_Values,
2675\end_layout
2676
2677\begin_layout Plain Layout
2678
2679   Config_File         => Config_File);
2680\end_layout
2681
2682\end_inset
2683
2684
2685\end_layout
2686
2687\end_inset
2688
2689
2690\end_layout
2691
2692\begin_layout Standard
2693The 
2694\emph on
2695Config_File
2696\emph default
2697 function call return either the default Yolk configuration file (
2698\emph on
2699configuration/config.ini
2700\emph default
2701) or a user specified configuration file given by the 
2702\emph on
2703--yolk-config-file
2704\emph default
2705 command line argument, so
2706\emph on
2707 
2708\emph default
2709starting for example the Yolk demo like this:
2710\end_layout
2711
2712\begin_layout LyX-Code
2713./yolk_demo --yolk-config-file /etc/yolk-config.ini
2714\end_layout
2715
2716\begin_layout Standard
2717will force the demo to look for the 
2718\emph on
2719/etc/yolk-config.ini
2720\emph default
2721 configuration file.
2722\end_layout
2723
2724\begin_layout Standard
2725There's a fully commented 
2726\emph on
2727config.ini.dist
2728\emph default
2729 file available in the 
2730\emph on
2731extras/
2732\emph default
2733 directory.
2734 I recommend taking a look at the Yolk demo application to see how the 
2735\emph on
2736Yolk.Configuration
2737\emph default
2738 package is used.
2739\end_layout
2740
2741\begin_layout Subsection
2742Get the AWS specific configuration settings
2743\end_layout
2744
2745\begin_layout Standard
2746On some occassions it might be necessary to get the AWS configuration object.
2747 This can easily be accomplished by calling the 
2748\emph on
2749Get_AWS_Configuration
2750\emph default
2751 function:
2752\end_layout
2753
2754\begin_layout Standard
2755\begin_inset Box Frameless
2756position "t"
2757hor_pos "c"
2758has_inner_box 1
2759inner_pos "t"
2760use_parbox 0
2761use_makebox 0
2762width "100col%"
2763special "none"
2764height "1in"
2765height_special "totalheight"
2766status open
2767
2768\begin_layout Plain Layout
2769\begin_inset listings
2770lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2771inline false
2772status open
2773
2774\begin_layout Plain Layout
2775
2776AWS_Config : constant AWS.Config.Object := 
2777\end_layout
2778
2779\begin_layout Plain Layout
2780
2781  Yolk.Configuration.Get_AWS_Configuration;
2782\end_layout
2783
2784\end_inset
2785
2786
2787\end_layout
2788
2789\end_inset
2790
2791
2792\end_layout
2793
2794\begin_layout Section
2795Yolk.Email
2796\end_layout
2797
2798\begin_layout Standard
2799Using 
2800\emph on
2801Yolk.Email
2802\emph default
2803 and the child package 
2804\emph on
2805Yolk.Email.Composer
2806\emph default
2807 you can build and send more or less any kind of email:
2808\end_layout
2809
2810\begin_layout Itemize
2811Plain text
2812\end_layout
2813
2814\begin_layout Itemize
2815Multipart/Alternative
2816\end_layout
2817
2818\begin_layout Itemize
2819Multipart/Mixed
2820\end_layout
2821
2822\begin_layout Standard
2823The package supports adding multiple SMTP servers, meaning you can add as
2824 many as you need, and the email will then be send via the first one that
2825 accepts it.
2826\end_layout
2827
2828\begin_layout Standard
2829The 
2830\emph on
2831Yolk.Email
2832\emph default
2833 package define 4 exceptions and 3 types.
2834 The facilities for actually constructing and sending the email are found
2835 in 
2836\emph on
2837Yolk.Email.Composer
2838\emph default
2839.
2840\end_layout
2841
2842\begin_layout Subsection
2843Exceptions
2844\end_layout
2845
2846\begin_layout Standard
2847These are:
2848\end_layout
2849
2850\begin_layout Itemize
2851
2852\emph on
2853Attachment_File_Not_Found
2854\emph default
2855.
2856 Is raised if a file attachment is not found at the given path.
2857\end_layout
2858
2859\begin_layout Itemize
2860
2861\emph on
2862No_Address_Set
2863\emph default
2864.
2865 Is raised if the address component of a To, Reply-To, From, Bcc/Cc header
2866 is missing.
2867\end_layout
2868
2869\begin_layout Itemize
2870
2871\emph on
2872No_Sender_Set_With_Multiple_From
2873\emph default
2874.
2875 Is raised when an email contains multiple From headers but no Sender header,
2876 as per RFC-5322, 3.6.2.
2877 http://tools.ietf.org/html/rfc5322
2878\end_layout
2879
2880\begin_layout Itemize
2881
2882\emph on
2883No_SMTP_Host_Set
2884\emph default
2885.
2886 Is raised if the SMTP host list is empty, ie.
2887 no SMTP host has been set for sending the email.
2888\end_layout
2889
2890\begin_layout Subsection
2891The Yolk.Email types
2892\end_layout
2893
2894\begin_layout Standard
2895When using 
2896\emph on
2897Yolk.Email.Composer
2898\emph default
2899 to build and send emails, three types declared in 
2900\emph on
2901Yolk.Email
2902\emph default
2903 are central:
2904\end_layout
2905
2906\begin_layout Enumerate
2907
2908\emph on
2909Character_Set
2910\end_layout
2911
2912\begin_layout Enumerate
2913
2914\emph on
2915Recipient_Kind
2916\end_layout
2917
2918\begin_layout Enumerate
2919
2920\emph on
2921Structure
2922\end_layout
2923
2924\begin_layout Standard
2925The 
2926\emph on
2927Character_Set
2928\emph default
2929 type define what character set is used when data is added to an email 
2930\emph on
2931Structure
2932\emph default
2933 object.
2934 For example looking at the 
2935\emph on
2936Yolk.Email.Composer.Add_From
2937\emph default
2938 procedure, we see that the 
2939\emph on
2940Charset
2941\emph default
2942 parameter defaults to 
2943\emph on
2944US_ASCII
2945\emph default
2946:
2947\end_layout
2948
2949\begin_layout Standard
2950\begin_inset Box Frameless
2951position "t"
2952hor_pos "c"
2953has_inner_box 1
2954inner_pos "t"
2955use_parbox 0
2956use_makebox 0
2957width "100col%"
2958special "none"
2959height "1in"
2960height_special "totalheight"
2961status open
2962
2963\begin_layout Plain Layout
2964\begin_inset listings
2965lstparams "basicstyle={\small\sffamily},frame=tblr,language=Ada,showstringspaces=false,tabsize=3,xleftmargin=1em,xrightmargin=1em"
2966inline false
2967status open
2968
2969\begin_layout Plain Layout
2970
2971procedure Add_From      
2972\end_layout
2973
2974\begin_layout Plain Layout
2975
2976  (ES        : in out Structure;       
2977\end_layout
2978
2979\begin_layout Plain Layout
2980
2981   Address   : in     String;       
2982\end_layout
2983
2984\begin_layout Plain Layout
2985
2986   Name      : in     String := "";       
2987\end_layout
2988
2989\begin_layout Plain Layout
2990
2991   Charset   : in     Character_Set := US_ASCII);
2992\end_layout
2993
2994\end_inset
2995
2996
2997\end_layout
2998
2999\end_ins

Large files files are truncated, but you can click here to view the full file