/docs/yolk.lyx
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 Lø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