Home

The ltxkeys Package

1. 0 00 e eee ee T MtxkeysQ newordkey eese esses 6 ltxkeys newordkeys 02 eee ee 6 ltxkeys newstylekey 000000 7 ltxkeys newstylekeys cece eee eee eee 9 ltxkeys nonlaunchkeys 5 27 ltxkeys nonoptionkeys 000 29 ltxkeys optionkeys socle ree 29 MltrxkeysOoptioHS o lem ar ree ees A NitikeysOorder n roll kid sede mecer reis 58 itskeys ordkey 2iielse sc d et 6 AltxkevB OEHKOETYS Lc eenecreveR en hr p ER HER 6 NIMES ci 1 ED 59 ltxkeys postsetkeys sees 25 ltxkeys presetkeys 00 0000 25 ltxkeys processoptions 0 0 eee 34 ltxkeys removebadkeynames 32 ltxkeys removedepkeys ee eee e eee 63 ltxkeys removeelements 61 ltxkeys removehandledkeys 30 ltxkeys removepostsetkeysS 25 ltxkeys removepresetkeys 25 ltxkeys removesavevaluekeys 23 ltxkeys replacedepkeys 4 63 ltxkeys replaceelements 61 ltxkeys reservekeyfamily 31 ltxkeys reservekeyprefix ol ltxkeys reservemacroprefix 31 MtxkeysO savevaluekeys ssesssss 23 MtxkeysOsavexfamilykeys 17 19 20 ltxkeys setaliaskey 2 cece eee 22 19th December 2011 Mtx
2. These check if key is defined with a prefix in prefs and in family in fams If the test proves that key is defined true text will be executed otherwise false will be executed PAGE 28 OF 66 The Itxkeys package 19th December 2011 6 Disabling keys New macro ltxkeys disablekeys 518 ltxkeys disablekeys prefs fams keys 519 ltxkeys disablekeys prefs fams keys Here keys is a comma separated list of keys to be disabled The macro ltxkeys disablekeys causes an error to be issued when a disabled key is invoked If the package option tracingkeys is true undefined keys are highlighted by ltxkeys disablekeys with a warning message Because it is possible to mix prefixes and families in ltxkeys disablekeys undefined keys may readily be encountered when disabling keys To see those undefined keys in the transcript file enable the package option tracingkeys The plain form of ltxkeys disablekeys disables the given keys instantly while the starred x variant disables the keys at AtBeginDocument Authors can use this command to bar users of their keys from calling those keys after a certain point 7 Option and non option keys Sometimes you want to create keys that can only appear in documentclass RequirePackage or usepackage and at other times you may not want the user to submit a certain set of keys via these commands The xwatermark package for example uses thi
3. 17 12 Expandable list parser New macro ltxkeys declarelistparser ltxkeys declarelistparser iterator parser def processor 1 1 iterator list processor iterator list processor 1191 1192 1193 1194 Given a parser or list separator parser the command ltxkeys declarelistparser can be used to define an expandable list iterator iterator The item processor processor should be a one parameter macro which will receive and process each element of list The optional exclamation mark determines whether or not the processor is actually expanded and executed in the current expansion context If is given the processor is expanded and executed otherwise it is merely given the elements as argument without expansion In general list isn t normalized but is expanded once before commencing the loop The list can be normalized by the command csv normalize of the catoptions package before looping The following example demon strates the concept The user can insert listbreak as an item in the list to break out of the iteration prematurely Examples ltxkeys declarelistparser 1195 ltxkeys declarelistparser iterator 1196 def do i 1 1197 The following example will yield x macro gt dofa do b dof c 1198 edef x iterator a b c do 1199 The following example will yield x macro gt abc 1200 edef x iterator a b c do 1201 The
4. ee ee eee eee eee 6 cross family keys see xfamily keys D declarevariables eese eee 42 declaring multiple options 33 defining multiple keys 13 15 bonu EUER 51 dependant keys see style keys disabling keyS olce tr LUE erre Rad 29 E ONWAEE nopevre pe pepe per berrHU vee aie PPP 3T environment keys 0 eee cece eee 35 G Weetvarvadie E ie ody ean ede iee 43 H handled keys RR eR RR ERE ee 29 I Ta r3RpubtUsEid c ev ee edged s 15 X fkeywal llsmnverig ee eer MORIR DIE phe4s 3T NESEBUVAITE cceli ooLeberiu s ecenek be ERE ERA d ifpathkeyskeyval cc eee eee 48 ifpathkeyskeyvalTF cc cee eee eee 48 SEP PACHEV SVE occ eroana E Ee dete 48 ifpathkeysvalTF 2 ee sec eer eee es 48 ROMMEL 5 5 3 essent md ope Ge Ca tO pd 37 Nae PF eireas ene 3T Mignorespacesafterend sees 38 illegal key name sees eese 31 initializing keys lee eto rper 26 is key defined eee aes 28 K key macrO Loieslec dad emia innn nuni a Enei 6 key polHt fS 23 p I ERE RES VA E EE 22 key prefix eec eee gale eA 4 RR RR ES 6 k vdepthirmit 112 22 fl 0 enr e ekle 21 kevstackiiHdb odl lessen eek per DIETS 21 Doll Ir EY L launching key8 sem e dk eem 26 ltxkeys addbadkeynames 005 32 ltxkeys adddepkeys ce cece eee eee 63 ltxkeys addhandledkeys 0
5. ltxkeys setkeys KV fam keya usevalue keyc keyb usevalue keya 437 4 5 Accessing the saved value of a key As mentioned earlier the pointers savevalue and usevalue are available for saving and using the values of keys within the command ltxkeys setkeys But suppose you have used savevalue within ltxkeys setkeys to set the value of a key how do you access that value outside of ltxkeys setkeys You can do this by using the following ltxkeys storevalue command New macro ltxkeys storevalue 438 ltxkeys storevalue pref fam key cs 439 ltxkeys storevalue pref fam key cs fallback Here cs is the macro defined or undefined that will receive the saved value of key The plain variant of this command will raise an error message if the value of the key wasn t previously saved while the plus variant will resort to the user supplied function fallback Only saved key values can be recovered by this command Examples ltxkeys storevalue 440 ltxkeys cmdkey KV fam needvalue keya left 441 def x 1 1xx 1 442 443 ltxkeys setkeys KV fam savevalue keya def y 1 1 444 ltxkeys storevalue KV fam keya tempa 445 ltxkeys storevalue KV fam keya tempb 446 latex error No value saved for key keya ehc 447 4 6 Pre setting and post setting keys New macros ltxkeys presetkeys ltxkeys postsetk
6. main2 sub2 subsub2 etc in which individual paths are separated by comma The quantity main is the main path and sub is the sub path etc Note that there is no forward slash before paths or main If the path is empty the default path dft main dft sub or the user supplied current path see later is used There is more about the default and current paths later in this guide The attrib is determined by the key called flag The flag determines the action the command pathkeys takes and must be a member of the set described in Table 2 The action specified by flag is if applicable on all the given paths taken on all the given paths See the table notes for the attrib s of the flags The attributes describe the arguments associated with the flags i e the quantities expected after the colon in the argument of pathkeys The na is the list of keys that are ignored by the flag s action If it is present in the attribute attrib part of pathkeys it must always be given in square brackets see note 16 1 For flags with x and signs the user should make sure there is no space between the flag and its star or plus sign such a space will not be zapped internally since syntactic matching is required Table 2 Flags and attributes for pathkeys No Flag Meaning 1 define Define the keys whether or not they already exist e 2 1 2 defin
7. to supply values for those keys Rather than simply issue an error for undefined keys when setting keys the ltxkeys package provides the undefined keys and undefined options handlers which are user customizable Other new concepts include definable keys cross family keys option keys non option keys handled keys pathkeys key commands key environments accessing the saved value of a key outside Because of the multitude of functions provided by the 1txkeys package it may actually slow down when executing some tasks depending on the task at hand The package option tracingkeys for example does slow down processing And automatically initiating keys after definition as done by the commands ltxkeys definekeys and ltxkeys declarekeys also affects processing speed so does launching keys which first presets absent keys with their default values before setting the current keys i e keys whose values are provided by the user at the moment of setting keys that belong to a family Then as in the xkeyval package there are the commands for presetting and post setting keys PAGE 3 OF 66 The Itxkeys package 19th December 2011 setkeys or similar commands and declaring multiple keys and options of all genre using only one command Note 1 1 It is not advisable to alias the commands of the xkeyval package to the commands of the ltxkeys package There
8. 83 84 PAGE 10 or 66 The Itxkeys package 19th December 2011 Choice keys check the user input against the nominations alt suggested by the author of a key The comma separated list alt is the list of admissible values of the key The starred x variant will convert user input to lowercase before checking it against the list of nominations in alt In all the above variants if the input is valid then the callback cbk will be executed If the user input isn t valid the non plus variants will flag an error while the plus variants will execute fn The variants will fully expand the user input before checking it against the nominations in alt The variant arises from the fact that sometimes macros are passed as the values of choice keys If mp is absent then ltxkeys choicekey uses chc pref fam key to hold the user input When alt has no literal form code or forward slash in it then it is expected to be of the familiar xkeyval package syntax Syntax of nominations for choice keys 85 choice1l choice2 etc If alt has code or in it then it is expected to have one of the following syntaxes Syntaxes of nominations for choice keys choice1 code callback1 keyparser choice2 code callback2 keyparser etc 86 87 88 89 90 i 91 or 92 7 choicei callbacki keyparser choice2 callback2 ke
9. Setting remaining keys The command ltxkeys setrmkeys which has both star x and plus variants is the coun terpart of setrmkeys of the xkeyval package New macro ltxkeys setrmkeys ltxkeys setrmkeys pref fam na ltxkeys setrmkeys pref fam na ltxkeys setrmkeys prefs fams na ltxkeys setrmkeys prefs fams na 376 377 378 379 The command ltxkeys setrmkeys sets in the given prefixes and families the remaining keys saved when calling the starred x variant of ltxkeys setkeys or ltxkeys setrmkeys na is again the list of keys that should be ignored i e not executed and not saved The unstarred variant of ltxkeys setrmkeys will report an error if a key is undefined The starred x variant of the macro ltxkeys setrmkeys like the starred x variant of ltxkeys setkeys ignores keys that it cannot find and saves them on the list saved for a future call to ltxkeys setrmkeys Keys listed in na will be ignored fully and will not be appended to the saved list of remaining keys 4 3 Setting aliased keys Aliased keys differ from style keys of subsection 3 4 Two keys may be aliased to each other such that when one is set the alias is automatically set with the same or a different value The concept is similar to but not identical with that of style keys The two aliases must all be in the same family and have the same key and macro pref
10. even if the keys originally have default values The default values of keys may not always be suitable Take for example the height and width of a graphics image For functions that are meant to handle generic images it would certainly be inappropriate to relieve the user of the need to call picture height and width without corresponding values To make a key a need value key simply attach the pointer needvalue to the key at definition time This pointer can be used only when defining keys and not when setting keys Need value keys 250 ltxkeys cmdkey KV fam mp needvalue keya blue 7 251 def x 1 1x 1x 1 252 253 ltxkeys setkeys KV fam keya 254 4 gt Error the author of keya designed it to require a user value See more about key pointers in subsection 4 4 3 10 Cross family keys There are times when it is required to use the same or nearly the same set of keys for different functions and purposes and thus for different key families and prefixes We call such keys cross family keys or xfamily keys Such keys bear the same names across key families and key prefixes For example the xwatermark package defines three functions xwmminipage xwmboxedminipage and xwmcolorbox using nearly the same set of keys In each of the three families the keys bear the same or similar names and they have similar callbacks The management of cross family keys can be simplified by
11. ltxkeys declarevariables 43 ltxkeys definekeys cece eee eee eee 14 ltxkeys definexfamilykeys 17 19 20 ltxkeys disablekeys 0 eee e eee 29 ltxkeys emptifyhandledkeys 30 PAGE 64 OF 66 The Itxkeys package MtxkeysQGeveryeoe sess eee eee 38 ltxkeys executeoptions 0 e ee 34 MltzkeysOflnQmAtCh or RR wee ERREUR 5T Nitzkeys setordeE cese d eter rA 58 ltxkeys handledkeys 0 004 30 Altxkeys0IfoBbe cieri ennie ER E Rete 5T NXlexteuscifsltcountIE sese Inf hes 58 MitzkeysOlffoumd eese ef ERR 56 NEtzkevsOLifincsyITSEIE 2 200 a NEtzkevsOifintsylistIE 2 22x94 58 AltxkeysOlfkeydefFT eer inden 28 XltxkeysOifkeydefTE ocino ennie 28 MltzkeysQlfpatOorn 2 ere REA 5T NURSE EOI L0 I gepbbbFYR re RP UO ERR ieee 56 Mtxkeys initializekeys s sues 26 ltxkeys kvnormalize sseslsessessse 59 ltxkeys kvnormalizeset 0 04 59 ltzkeys launchkeys c esee essences 26 ltxkeys makeoptionkeys 29 ltxkeys newbiboolkeys eee eee 10 ltxkeys newboolkey eee eee eee 9 ltxkeys newboolkeys 2 cece eee eee 10 ltxkeys newchoicekey cece eee eee 11 ltxkeys newchoicekeys 000 13 ltxkeys newcemdkey cc cee eee eee eee eee 6 ltxkeys newcmdkeys
12. putframe true end document Example Key environment ltxkeysenv testenv 1 right A cmd xwidth 2cm cmd ywidth 1 5cm cmd body cmd needvalue author null bool boola false 4 ltxkeys iffound 1 in right left then else latex error Unknown text alignment type 1 ehd fi centering fbox parbox keyval xwidth usename ragged 1 keyval body ifkeyval boola then color red fi fbox parbox keyval ywidth usename ragged 1 keyval body normalcolor val ifval etc are unavailable in ltxkeys everyeoe Hence we save the value of author here protected edef quoteauthor valfauthor Re initialize ltxkeys everyeoe ltxkeys everyeoe ltxkeys everyeoe ignorespacesafterend ltxkeys everyeoe endgraf vskip baselineskip centerline itshape quoteauthor Just to test parameter use inside ltxkeysenv def testmacroa 1 aaat 1 HL def testmacrob 1 1bbb J begin document begin testenv xwidth 5cm ywidth 4cm boola true author Cornelius Tacitus textup 55 1207 AD body Love of fame is the last thing even learned men can bear PAGE 39 OF 66 The Itxkeys package 19th December 2011 704 to be parted from 705 706 end testenv 707 end document Examples Key environment The following line has parameter delimiters nil and mil 4 ltxkeysglobal ltxkeysrobust ltxkeysenv envframebox i 3 default l
13. 1173 1174 1175 The command ltxkeys ifcase tests teststr against case i If a match is found the case i s callback cbk i is returned in the macro currmatch and true is executed If at the end of the loop no match is found ltxkeys ifcase returns empty currmatch and executes false The command ltxkeys findmatch works like ltxkeys ifcase but executes the fallback fn instead of true or false when no match is found 17 6 Is the number of elements from a sublist found in a csv list gt n New macro MtxkeysOifincsvlistTF 1176 ltxkeys ifincsvlistTF Aparser nr sub main true false 1177 ltxkeys ifincsvlistTF Aparser nr sub main true false The command ltxkeys ifincsvlistTF checks if the number of elements of parser separated csv list sub found in main is equal or greater than nr The argument main is the main list and sub is the sublist of test strings Normally sub will be a user input and main the list of nominations Neither main nor sub is expanded in the test If the test is true ltxkeys itemspresent returns all the elements found ltxkeys nritems returns the num ber of elements found and true is executed If the test fails ltxkeys itemspresent re turns empty ltxkeys nritems returns 1 and false is executed The starred x variant of ltxkeys ifincsvlistTF will turn both input and nominations to lowercase before t
14. 9 Reserving and unreserving key path or bases By key path we mean the key prefix default is KV key family generally no default and macro prefix default is dependent on the type of key However when dealing with pathkeys see section 16 the term excludes the macro prefix You can reserve key path or bases i e bar future users from using the same path or bases by the following commands Once a key family or prefix name has been used it might be useful barring further use of those names For example the ltxkeys package has barred users from defining keys with key family 1txkeys and macro prefix ltxkeysQ PAGE 30 or 66 The Itxkeys package 19th December 2011 New macros ltxkeys reservekeyprefix ltxkeys reservekeyfamily etc 533 ltxkeys reservekeyprefix list 534 ltxkeys reservekeyprefix list 535 ltxkeys reservekeyfamily list 536 ltxkeys reservekeyfamily list 537 ltxkeys reservemacroprefix list 538 ltxkeys reservemacroprefix list Here list is a comma separated list of bases The starred x variants of these commands will defer reservation to the end of the current package or class while the unstarred variants will effect the reservation immediately As the package or class author you may want to defer the reservation to the end of your package or class Users can at their own risk override reserved key bases simply by issuing the package boolean op tion reserven
15. cece cece eee eee 27 non option keyS lee cedi e e tw 29 o Option key S i ise code nemete ine Vaden PR 29 ordinary keys ord esses esses 6 P package options sss esee 4 32 Packagesss csi desde a oops eder etg s am toolS 4 on be ener GrESED a 2 catoptions ce iens 2 21 35 60 63 GbOOlIDOX me Rhe REIR RIS reas 62 keycommand elio R34 EI ELE EY 35 keyreader ell wwepirIr lae pes dereud 3 keyval i slnenerendenePuvenesSe4 epe 1 2 kvoptions pateh olo sete ue eae tent dn 2 ltxkeys 1 4 7 10 20 22 25 27 30 31 34 38 43 55 59 60 62 ltxtools ba880 eer br tote 60 pathkeyS cubre ge elie desde pies aes 5 43 skeycommand sisi ese Phoned eee 35 xkeyval 1 4 6 7 9 11 13 21 22 32 56 PAGE 65 or 66 The Itxkeys package SVM Pic sche prbh pre DEDI tale Sea dears ONDE 2 xwatermark cere ees 2 4 17 19 29 boog0 7 PR cnm 44 pathkeys ccce idee aed pate mens 43 pathkeys addtodefaultpath 52 pathkeys changedefaultpath 52 pathkeys currentpath esse eee ee 52 pathkeys pathhistory esse eee ee 52 MpathkeysOpopcurrentpath ssssees 52 pathkeys pushcurrentpath 52 pathkeys storevalue cee cece eee eee 48 pathkeys usedefaultpath 00 52 pathkeyskeyval cece eee eee eee eee 48 Apathieysuald lslszszbreec k
16. fn 55 56 57 58 In these commands if mp is given the command mp key will hold the current user input for the key at key setting time otherwise the user input will be available in bool pref fam key If mp is specified a boolean of the form if mp key will be created at key definition which will be set by ltxkeys setkeys according to the user input If mp is not specified a boolean of the form ifbool pref fam key will instead be created The user input for boolean keys must be in the set true false The callback cbk is held in the command pref fam key which is executed if the user input is valid The plus variant of ltxkeys boolkey and ltxkeys newboolkey will execute fn in place of cbk if the user input isn t in true false the plain form will issue an error in this case 3 5 1 Boolean keys that share the same attributes The commands ltxkeys boolkey and ltxkeys newboolkey can be used to introduce boolean keys keys that share the same path or bases key prefix key family and macro prefix and callback cbk Just replace key in these commands with the comma separated list keys Because some users might prefer to see these commands in their plural forms when defining several keys with the same callback we have provided the following aliases 59 ltxkeys boolkeys pref fam mp keys dft cbk 60 ltxkeys boolkeys
17. keyb yyy keyc 4 7 Initializing keys 484 ltxkeys initializekeys prefs fams na This presets all the keys previously defined in families fams with their default values it ignores keys listed in na If na is a list of key value pairs the key names are extracted from the list before the family keys are initialized Any key value pairs in na are not set at all All keys defined by ltxkeys definekeys and ltxkeys declarekeys are automatically instantly initialized except slave alias and dependant keys Alias and dependant keys aren t initialized in this case in order to avoid cyclic re entrance of ltxkeys setkeys The command ltxkeys initializekeys can be used in place of ltxkeys executeoptions since ltxkeys executeoptions similar to TFX kernel s ExecuteOptions fulfils the sole purpose of setting up default values of options Keys defined via ltxkeys definekeys and ltxkeys declarekeys don t have to be initialized since they re automatically initialized at definition time Note 4 1 Keys that have been processed by ltxkeys processoptions i e keys submitted by the user as package or class options via documentclass or usepackage can t be initialized or launched see subsection 4 8 below for the meaning of launched keys This is to avoid unwittingly setting keys to their default values after the user has submitted them as package or class options This means that option k
18. myspecialkeys in the above example doesn t actually exist it is only meant for illustration here But handled keys may be introduced by the user to serve this purpose This will be the set of keys for which special actions may apply at key setting time see section 8 Note 4 3 To see what the parameter texts 1 and 1 above stand for run the following code on your own and note the outcome of show KV fam keyd The characters 1 will turn out to be the parameter text which can be used to access the current values of keys keyd and keye after they have been defined on the fly And 1 will be the parameter text of the arbitrary function x If you do show KV fam keyd you ll notice that the parameter texts have been reduced by one level of nesting Examples ltxkeys unknownkeyhandler def myspecialkeys keyc keyd keye ltxkeys unknownkeyhandler KV fam expandtwoargs in 3 myspecialkeys ifin ltxkeys ordkey 1 2 3 4 Ndef x 1 HHH xx 1 3 else ltxmsg warn Unknown key 3 with value InnocentVal in family 2 ignored ehd 506 507 508 509 510 511 fi F ltxkeys setkeys KV fam keyd aaa keye bbb show KV fam keyd 512 513 514 515 5 Checking if a key is defined 516 ltxkeys ifkeydefTF prefs fans M key H true H false 517 ltxkeys ifkeydefFT prefs fams key false true
19. 1 207 Boolean key without callback 208 bool keyc true 209 Boolean key with callback 210 bool keyd true ifmp keyd tempswatrue else tempswafalse fi 211 Style key with callback but no dependants 212 sty keye aaa code def y 1 1yyy 1 213 Style key with callback and dependants keyg and keyh 214 sty keyf blue def y 1 1 1 PAGE 15 OF 66 The Itxkeys package 19th December 2011 215 cmd gt keyg gt parentval gt def z 1 1 1 H 1 216 ord gt keyh gt KV fam keyf value 217 4 Choice key with simple nominations and callback The function 218 Norder is generated internally 219 choice keyi left right center center 220 edef shoot ifcase order O or 1 or 2 fi 221 Choice key with complex nominations 222 choice keyj 223 center code def mp textalign center 224 left code def mp textalign flushleft 225 code can be omitted 226 right def mp textalign flushright 227 justified let mpG textalign relax 228 229 center def yy 1 1yy 1 230 ord keyk letcstocsn func as defined by user 231 Notice the gt gt used for the attributes of the dependant keys keyg and keyh of style key keyf Dependent keys come as the last attributes of a style key and they dependant keys are separated by comma The default value of the dependant key keyg will in this example be whatever is submitted for keyf
20. 1txkeys package preserve outer braces but sometimes it is needed to rid a token of one or more of its outer braces This can be achieved by the following commands New macros ltxkeys stripNouterbraces ltxkeys stripallouterbraces etc 1229 ltxkeys stripNouterbraces nr token 1230 ltxkeys stripallouterbraces token 1231 ltxkeys stripallouterbracesincs cmd The command ltxkeys stripNouterbraces strips nr number of outer braces from token The command ltxkeys stripallouterbraces strips all outer braces from token The com mand ltxkeys stripallouterbracesincs strips all the outer braces in the top content of the command cmd All these commands are expandable Normally token wouldn t be expanded by these commands in the process of stripping off outer braces Examples ltxkeys stripNouterbraces ltxkeys stripallouterbraces etc 1232 toks expandafter expandafter expandafter 1233 ltxkeys stripNouterbraces 2 y 1234 edef x unexpanded expandafter expandafter expandafter 1235 ltxkeys stripNouterbraces m y 1236 edef x ltxkeys stripallouterbraces y 48 To do list This section details additional package features that may become available in the foreseeable future User views are being solicited in regard of the following proposals 18 1 Patching key macros Patching the macro of an existing key instead of redefining the key etoolbox package s patchcm
21. 3 Pathkeys command abbreviations Command Abbreviation Command Abbreviation pathkeysval pkv pathkeyskeyval pkkv ifpathkeysval ifpkv ifpathkeyskeyval ifpkkv ifpathkeysvalTF ifpkvTF ifpathkeyskeyvalTF ifpkkvTF The user isn t constrained to use the short form commands of Table 3 He she can define his her own short forms by using the command pathkeys makeshortcmds which has the syntax PAGE 51 OF 66 The Itxkeys package 19th December 2011 1033 pathkeys makeshortcmds short 1 long 1 short n long n where short i and long i are the short new and long existing aliases of the command i The equality sign is mandatory here You don t have to in fact you shouldn t call pathkeys useshortcmds after calling pathkeys makeshortcmds Example pathkeys makeshortcmds 1034 pathkeys makeshortcmds kval pathkeyskeyval ifkvalTF ifpathkeyskeyvalTF 16 2 Default and current paths New macros pathkeys currentpath etc pathkeys addtodefaultpath path pathkeys changedefaultpath path pathkeys currentpath path pathkeys usedefaultpath pathkeys pushcurrentpath pathkeys popcurrentpath pathkeys pathhistory 1035 1036 1037 1038 1039 1040 1041 If the key path is empty then the current path will be used and if there is no current path the default path will be used The default path is dft main dft sub This
22. 4 7 Initializing keys 26 3 3 1 Command keys that share the 4 8 Launching keys 26 same attributes 7 4 8 1 Non initialize and non launch 3 4 Style keys 7 Sek ee Be ike a 27 3 4 1 Style keys that share the same 4 9 Handling unknown keys and options 27 abteIbubeE eue Lus 9 3 5 Booleankeys g 5 Checking if a key is defined 28 3 5 1 Boolean keys that share the same attributes g 6 Disabling keys 29 36 Choice keys a oo ao LLTI 10 7 Option and non option keys 29 3 6 1 Choice keys that share the 8 Handled keys 29 same attributes 13 3 7 Defining boolean and command keys 9 Reserving and unreserving key path or with one command 13 bases 30 3 8 Defining all types of key with one gommand s c s p GRE a RS 15 10 Bad key names 31 3 8 1 Defining keys of common type with ltxkeys declarekeys 16 11 Declaring options 32 The package is available at http mirror ctan org macros latex contrib ltxkeys This user manual corresponds to version 0 0 3 of the package 1 The University of Central Lancashire Preston UK Email address for all 1txkeys package related matters amusa22Q gmail com The Itxkeys package 19th December 2011 11 1 Options that share the same attributes 33 17 5 ifcase for arbitrary strings 57 11 2 Declaring all types of option with one 17 6 Is the number of elements from a sub eoiinand s e e r oo dong 33 list f
23. The Itxkeys package 19th December 2011 envarg which expects as argument the corresponding numeral of the parameter text For ex ample Nenvarg i and envarg 3 refer to the first and third arguments of the environment respectively Examples are provided later The current values of environment s keys can always be accessed in enddefn But how do we access the current values or states of keys while in begdefn and enddefn To this end the commands val ifval ifvalTF keyval ifkeyval and ifkeyvalTF are provided They have the following syntaxes New macros val ifval ifvalTF etc The following commands don t first confirm that the key exists before attempting to obtain its current value or state They are expandable val key ifval boolkey then true else false fi ifvalTF boolkey true false 4 The following commands first confirm that the key exists before attempting 4 to obtain its current value or state They are expandable if the key is defined keyval key ifkeyval boolkey then true else false fi ifkeyvalTF boolkey true false The command val yields the current value of a command or environment key irrespective of the type of key Its argument should exclude the key command name key prefix key family and macro prefix The command ifval expects as argument a boolean key name boolkey without the command name key prefix key family and macr
24. are to be set after setting other keys in every run of ltxkeys setkeys for the given key prefix and family ltxkeys addpostsetkeys is an alias for ltxkeys postsetkeys The commands Macros ltxkeys removepresetkeys pre f fam H keys ltxkeys removepostsetkeys pref fam keys remove keys from preset and post set lists respectively The commands Macros ltxkeys undefpresetkeys pref fam ltxkeys undefpostsetkeys pref fam respectively undefine all preset and post set keys in the given family Logically you can t enter the same key twice in either preset or post set list in the same family and prefix Examples ltxkeys presetkeys ltxkeys postsetkeys etc ltxkeys definekeys KV1 fam1 mpe 7 keya left def x 1 1x 1 needvalue keyb right keyc center keyd ltxkeys presetkeys KV1 fami keya flushleft keyb flushright ltxkeys postsetkeys KV1 fam1 keyd flushleft Eventually only keya will be preset ltxkeys removepresetkeys KV1 fami keyb flushright 4 Because of the and signs on ltxkeys setkeys all unknown PAGE 25 OF 66 19th December 2011 The Itxkeys package 19th December 2011 481 4 keys those with prefix KV2 and in family fam2 will be saved in 482 the list of remaining keys and can be set later with ltxkeys setrmkeys 483 ltxkeys setkeys KV1 KV2 fam1 fam2 keyd keya xxx
25. at setting keys it has to be explicitly indicated there The pointers savevalue and usevalue can both be used when setting keys but PAGE 22 OF 66 The Itxkeys package 19th December 2011 not the pointer needvalue The presence of the pointer needvalue when setting keys prompts an error Here is an interesting example and proof of concept of pointers 400 ltxkeys stylekeys KV fam 7 401 needvalue keya savevalue needvalue keyb needvalue savevalue keyc 402 Left 403 1 here refers to the value of the dependant key at the 404 time it is being set 405 ord savevalue keyb parentval edef y 1 1xx unexpanded 1 406 cmd keyc center 407 H 408 1 here refers to the value of the parent key at the time 409 it is being set 410 def x 1 1xx 1 411 412 ltxkeys setkeys KV fam 413 savevalue keya def y 1 1 414 savevalue keyb usevalue keya 415 keyc usevalue keyb 416 F If you have to save the values of many keys then the above scheme of placing savevalue on keys at key setting time can be avoided by using the following commands New macros ltxkeys savevaluekeys ltxkeys addsavevaluekeys etc ltxkeys savevaluekeys pref fam list ltxkeys addsavevaluekeys pref fam list ltxkeys removesavevaluekeys pref fam list ltxkeys undefsavevaluekeys pref fam ltxkeys undefsavevaluekeys pref fam ltxke
26. can be changed by the commands pathkeys addtodefaultpath and pathkeys changedefaultpath The current path can be declared by providing an argument to the command pathkeys currentpath The default path can be made the current path by invoking the command pathkeys usedefaultpath which is parameterless It isn t mandatory but it is useful to first push the prevailing path before changing it This can be done by calling the parameterless command pathkeys pushcurrentpath When you re done with the current path you can revert to the path before the current path by calling the command pathkeys popcurrentpath You can get the entire history of path changes from the container pathkeys pathhistory which is useful in complex situations However it should be noted that pathkeys pathhistory doesn t contain a chronological order of path changes if a path is already contained in it it wouldn t be added again Before the current path is resorted to the path for the commands pathkeys pathkeysval ifpathkeysval etc must be empty i e no main and no subs Therefore in any given setting the path that is dominant can be made current so that it isn t given in pathkeys pathkeysval ifpathkeysval etc The non dominant paths could then be listed in full Of course there can t be more than one current path Examples pathkeys currentpath etc 1042 newcommand myframebox 1 1043 pathkeys currentpath KV frame framebo
27. current user input at key setting time otherwise i e if mp is absent the user input 5 The commands ltxkeys key and ltxkeys newkey aren t user commands 6 The key path is also called the key bases PAGE 6 OF 66 The Itxkeys package 19th December 2011 will be available in the macro cmd pref fam key The command pref fam key is the key macro and will hold the callback cbk This type of key is traditionally called command key a name that most likely emanated from the xkeyval package because it gives rise to the macro mp key but in the 1txkeys package even boolean style and choice keys are associated with this type of macro 3 3 1 Command keys that share the same attributes The commands ltxkeys cmdkey and ltxkeys newcmdkey can be used to introduce command keys keys that share the same path or bases key prefix key family and macro prefix and callback cbk Simply replace key in these commands with the comma separated list keys Some users might prefer to see these commands in their plural forms when defining several keys with the same callback We have therefore provided the following aliases New macros ltxkeys cmdkeys MtxkeysOnewcmdkeys 19 ltxkeys cmdkeys pref fam mp keys df t cbk 20 ltxkeys newcmdkeys pref fam mp keys dft cbk Style keys Style keys are keys with dependants i e keys that are process
28. determines if information should be logged in the transcript file for some tasks in the package note 1 1 keyparser The list parser used by some internal loops in defining keys keydepthlimit 4 This is used to guard against erroneous infinite re entrance of the package s key setting commands The default value of 4 means that neither of these commands can ordinarily be nested beyond level 4 Continued on next page 3 A user of version 0 0 1 of the 1txkeys package had sought to do this Passing 1txkeys package options via documentclass implies that the package is loaded after documentclass As mentioned elsewhere the 1txkeys package can be loaded before or after documentclass PAGE 4 OF 66 The Itxkeys package 19th December 2011 Continued from last page Option Default Meaning reservenopath false The path or roots or bases of a key is the combination of key prefix key family and macro prefix but when dealing with pathkeys see section 16 the term excludes the macro prefix These can be reserved and unreserved by any user by the tools of section 9 Subsequent users can at their own risk override all previously reserved paths by enabling the package s boolean option reservenopath allowemptypath false Allow the use of empty key prefix and family This isn t advis able but some pre existing packages might have used empty key prefixes and
29. document error to signify that a token has been output outside these situations And one source of problem with ifpathkeysval and ifpathkeyskeyval is to omit then after their argument If you find yourself typing long key paths and the commands pathkeysval and pathkeyskeyval etc repeatedly there is help ahead on how to reduce estate when using pathkeys The following provide our first examples of pathkeys and a demonstration of some of the commands associated with pathkeys Examples Pathkeys pathkeys fam subfam subsubfam define cmd xwidth tempdima def y 1 1lyy 1 cmd keya def cmda 1 1 bool putframe true 907 908 909 910 J pathkeys fam subfam subsubfam set putframe true keya pathkeys fam subfam subsubfam ifdef xwidth def x T def x F pathkeys fam subfam subsubfam famx subfamx subsubfamx ifkeyonpath xwidth def x T def x F pathkeys fam subfam subsubfam print value xwidth z pt pathkeys fam subfam subsubfam store value keya cmd pathkeys fam subfam subsubfam add value keya def cmdb 1 1 pathkeys storevalue fam subfam subsubfam putframe cmd edef x ifpathkeysvalTF fam subfam subsubfam putframe T F edef x ifpathkeysval fam subfam subsubfam putframe then T else F fi edef x ifpathkeysval fam subfam subsubfam putframe then T else F fi 4 xputframe is undefined What does the following return edef x pathkeysval fam subfam subsubfam xputf
30. error message is flagged Run the following example and do show cmdb and show cmdd Example ltxkeys ordkey ltxkeys ordkey KV fam keya def cmda i aa 1 def cmdb 1 1bb 1 ltxkeys ordkey KV fam keyb def cmdc 1 cc 1 def cmdd 1 1dd 1 ltxkeys setkeys KV fam keya keyb 12 13 14 3 2 1 Ordinary keys that share the same attributes The commands ltxkeys ordkey and ltxkeys newordkey can be used to introduce ordinary keys keys that share the same path key prefix key family and macro prefix and callback cbk All that is needed is to replace key in these commands with the comma separated list keys Because some users might prefer to see these commands in their plural forms when defining several keys with the same callback we have provided the following aliases The internal coding remains the same and no efficiency has been lost in generalization New macros ltxkeys ordkeys ltxkeys newordkeys 15 ltxkeys ordkeys pref fam keys dft cbk 16 ltxkeys newordkeys pref fam keys dft cbk 3 8 Command keys New macros ltxkeys cmdkey ltxkeys newcmdkey 17 ltxkeys cmdkey pref fam mp key dft cbk 18 ltxkeys newcmdkey pref fam mp key dft cbk Here the optional quantity mp is the macro prefix If mp is given the command mp key will hold the
31. nomin If the input is valid the user input is returned in val and the numerical order starting from zero of the input in the nominations is returned in order If the input isn t valid the user input is still returned in val but 1 is returned in order parser is the list parser The starred x variant of ltxkeys checkchoice will convert input into lowercase before checking it against the nominations The plus variant of ltxkeys checkchoice expects two branches true and false of callback at the end of the test The non plus variant expects only one branch true and will return error if the input is invalid The commands ltxkeys checkinput and CheckUserInput apply to comma separated lists of nominations nomin and they always convert input to lowercase before checking it against the nominations nomin The macro ltxkeys checkinput expects two branches of callback while CheckUserInput expects no callback Instead CheckUserInput will toggle the internal boolean ifinputvalid to true if the input is valid and to false otherwise The internal boolean ifinputvalid could then be called by the user after the test 17 3 Does a test string exist in a string New macros ltxkeys in ltxkeys iffound ltxkeys in teststr str ltxkeys in teststr str true false ltxkeys iffound teststr in str then true else false fi 1168 1169 1170 The unstarred varia
32. pref fam mp keys df t cbk fn 7 This differs from the system in the xkeyval package PAGE 9 OF 66 The Itxkeys package 19th December 2011 61 ltxkeys newboolkeys pref fam mp keys dft cbk 62 ltxkeys newboolkeys pref fam mp keys dft cbk fn 3 5 2 Biboolean keys New macros ltxkeys biboolkeys ltxkeys newbiboolkeys ltxkeys biboolkeys pref fam mp b11 b12 dft cbk1 cbk2 ltxkeys biboolkeys pref fam mp b11 b12 dft cbk1 cbk2 fn ltxkeys newbiboolkeys pref fam mp b11 b12 dft cbk1 cbk2 ltxkeys newbiboolkeys pre am mp b11 b12 dft cbk1 cbk2 fn 63 64 65 66 67 Biboolean keys always assume opposite states when one is true the other is automatically toggled to false and vice versa Think of the options draft and final in a document class but note that traditional document classes don t currently use biboolean keys The callback cbk1 belongs to the boolean key b11 while cbk2 is of b12 The plus variant of ltxkeys biboolkeys will execute fn in place of cbk1 or cbk2 if the input is not in true false the plain form will issue an error in this case Biboolean keys have equal symmetry i e they can call each other with equal propensity and they won t bomb out in an infin
33. the ltxkeys nonlaunchkeys command undefined keys are simply ignored by ltxkeys nonlaunchkeys Note 4 2 The command ltxkeys nonlaunchkeys doesn t mean that the keys in keys can no longer be set via the command ltxkeys setkeys it simply implies that keys appearing in ltxkeys nonlaunchkeys will not be reinitialized to their default values when members of their class are being launched or reinitialized The command ltxkeys noninitializekeys is an alias for ltxkeys nonlaunchkeys 4 9 Handling unknown keys and options You can use the macro ltxkeys unknownkeyhandler to declare to the ltxkeys package the course of action to take if while setting keys it discovers that a key is undefined or unknown The command ltxkeys unknownoptionhandler applies to unknown options see section 11 The syntax of these commands is New macros ltxkeys unknownkeyhandler ltxkeys unknownoptionhandler 490 ltxkeys unknownkeyhandler prefs fams cbk 491 ltxkeys unknownoptionhandler pref lt fam gt cbk The callback cbk signifies the action to take when an unknown key or option is encountered The default cbk is to log the keys and in each run warn the user of the presence of unknown keys The same cbk can be used across key prefixes prefs and families fams You can use 1 or CurrentPref in this macro to represent the current key prefix 2 or CurrentFam for the cur rent family 3 or CurrentKey for th
34. variant of ltxkeys choicekey will convert the user input to lowercase before checking alt and executing the callbacks The plus variant will execute fn in place of cbk if the user input isn t in alt bin has e g the syntax userinput order where userinput will hold the user input in lowercase if the starred x variant of ltxkeys choicekey is called and order will hold the serial number of the value in the list of nominations alt starting from 0 If the input isn t valid userinput will still hold the user input but order will be 1 ltxkeys choicekey KV fam keya 7 There are no callbacks for these simple nominations center right left justified center lt default value def x 1 2 1 1 2 b ltxkeys choicekey KV fam mp0 keya userinput order 7 center right left justified J center def x 1 2 1 1 2 7 ML latex error Inadmissible value detokenize 1 for keya ehc i ltxkeys choicekey KV fam mp0 keyb userinput order 7 There are callbacks for these nominations land code def x 1 1 1 1 air code edef z expandcsonce ltxkeys tval sea code edef myinput cpttrimspaces 1 space code letcsntocs 1 earth relax J center def z 1 2 1 1 2 7 ML latex error Inadmissible value detokenize 1 for keya ehc J ltxkeys choicekey KV fam mp0 keyb userinput ord
35. 05 30 ltxkeys addpostsetkeys e esse eee 25 ltxkeys addpresetkeys cece ee eee 25 ltxkeys addsavevaluekeys zd ltxkeys afterprocessoptions 35 ltxkeys badkeynames 0 eee eee 32 ltxkeys beforeprocessoptions 35 Ltxkeys biboolkeys 2 1 60 c en eg 10 MltxkeysOboolk y 2 ele merece caine es 9 MtxkeysOboolkeys eese eee eeees 10 ltxkeys checkchoice ce eee eee eee 56 ltxkeys checkinput 0 cess eee eee 56 ltxkeys choicekey eee ee eee eee ee 11 ltxkeys choicekeys cece eee ee eee 13 VItikeysOcu4dkEed o ernai ereenn ce Metta dees 6 MltxkeysOcmdieys lll sules ie re RP ERI T ltxkeys commacheckchoice 06 56 MtxkeysO commanormalize ssss s 59 ltxkeys commanormalizeset 59 ltxkeys declarebooloption 33 ltxkeys declarebooloptions 33 ltxkeys declarechoiceoption 33 ltxkeys declarechoiceoptions 33 ltxkeys declarecmdoption BE ltxkeys declarecmdoptions 33 ltxkeys declarekeys 0 15 16 ltxkeys declarelistparser 60 ltxkeys declaremultitypeoptions 34 ltxkeys declareoption eee eee 32 ltxkeys declareordoption 33 ltxkeys declareordoptions BE
36. A iflacus 1 dolacus else ltxkeys afterprocessoptions RequirePackage 1 mypackage fi In this example 1 refers as usual to the user input for key keya Here we assume that the values of keya will be the key value pairs for options of mypackage The loading of mypackage will be determined by whether the user input for keya is empty or not That is why keya has an empty default value More complex application scenarios can of course be easily created 14 Key commands and key environments Key commands and environments are commands and environments that expect key value pairs as input in addition to any number of possible nine conventional arguments Key commands and environments have already been introduced by the keycommand and skeycommand packages but the inherent robustness of the 1txkeys provides another opportunity to re introduce these features here The syntax here is also simpler and the new featureset has the following advantages over those in keycommand and skeycommand packages 9 The command iflacus whose argument is delimited by dolacus tests for emptiness of its argument PAGE 35 or 66 The Itxkeys package 19th December 2011 a The defined commands and environments can have up to nine conventional parameters in addition to the key value pairs b Anyone or all of the nine command or environment parameters can be delimited c All the various types of
37. As indicated in subsection 3 4 the function KV fam keyf value has a longer shelf life than parentval Notice also the syntax keyi left right center for the choice keys keyi and keyj It says that the alternate admissible values for keyi are left right center and justified similarly for key keyj Defining keys of common type with ltxkeys declarekeys If you have to define keys of the same type with the command ltxkeys declarekeys then the following syntax allows you to avoid entering the key types repeatedly Macro ltxkeys declarekeys ltxkeys declarekeys keytype pref fam mp keyname df t cbk another set of key etc ltxkeys declarekeys keytype pref fam mp keyname df t cbk another set of key etc i Examples ltxkeys declarekeys 240 ltxkeys declarekeys bool KV fam np 241 keya true def x 1 1 1 1 242 keyb true 243 keyc true def y 1 1lyyy 1 244 245 ltxkeys declarekeys sty KV fam mp 246 keyd xxx def y 1 1yyy 1 247 4 keyf is a dependant of keye 248 keye blue def y 1 1 1 cmd gt keyf gt parentval gt def z 1 GIHEHEET HET HIBWBET PAGE 16 OF 66 The Itxkeys package 19th December 2011 249 3 9 Need value keys Sometimes you may want to create keys for which the user must always supply his her own values
38. Options are keys with a special default family There might be a reason to handle unknown options separately from unknown keys Table 2 notes These notes describe the attributes of handlers i e what are required to be specified in the command pathkeys after the colon appear in square brackets e g sign na keys are the keys to be ignored they must keya 2 1 See attribute in note 16 1 2 2 Same as for define flag 7 3 Same as for define flag 2 4 The flag declareoptions simply signifies the user s aim to define definable options it has nothing to do with the starred x variant of the command ltxkeys declareoption of section 11 The attribute is the same as for define flag 25 key value value value D MES MES MN key 7 key key key value pairs see subsection 4 6 pairs see subsection 4 6 pairs see subsection 4 6 pairs see subsection 4 6 PAGE 45 OF 66 The Itxkeys package 19th December 2011 na keys see subsection 4 2 na keys see subsection 4 2 keys see section 13 na keys see subsection 4 2 na keys see section 13 2 25 The attribute is a comma separated key list 2 26 Comma separated key list 2 27 The arguments of the unknown key or option handler are the main path subpaths separated by forward slash key name and the current key value see subsection 4 9
39. The key or option handler can have up to a maximum of 4 arguments Note 16 1 The syntax for specifying keys to be defined by pathkeys is see subsection 3 8 Syntax for defining keys in pathkeys pathkeys path define keytype keyname dft cbk another set of key attributes etc 861 862 863 864 J 865 The default value dft and the callback cbk can be absent in all cases keytype may be any member of the set ford cmd sty sty bool choice The star x in sty has the same meaning as in ltxkeys stylekey subsection 3 4 namely undefined dependants will be defined on the fly when the parent is set executed Example Syntax for defining pathkeys Define keys on only one path pathkeys fam subfam subsubfam define cmd keya defaultval def cmda 1 1 bool keyb true i 4 Define keys on multiple paths Mpathkeysifami subfami subsubfami fam2 subfam2 subsubfam2 define cmd keya defaultval def cmda 1 1 bool keyb true 866 867 868 869 870 871 872 873 874 J 875 PAGE 46 oF 66 The Itxkeys package 19th December 2011 Choice keys must have their names associated with their nominations i e admissible values in the format keyname nominations as below see also subsection 3 8 Syntax for defining choice keys in pathkeys 4 keya is a choice key with simple nominations and callback while keyb 876 4 is
40. a choice key with complex nominations The function order is generated internally by the package for choice keys pathkeys fam subfam subsubfam define choice keya left right center center edef x ifcase order O or 1 or 2 fi choice keyb center code def textalign center left code def textalign flushleft 4 code can be omitted as in right def textalign flushright justified let textalign relax center def x 1 1xx 1 877 878 879 880 881 882 883 884 885 886 887 888 889 The na keys if they are present in the attribute of pathkeys must always be given in square brackets They can come either before or after the key value list to be set in the current run For example pathkeys fam subfam subsubfam define cmd keya xx def cmda 1 1 bool keyb true 890 891 892 Set keya and ignore keyb pathkeys fam subfam subsubfam set keya zz keyb true keyb or pathkeys fam subfam subsubfam set keyb keya zz keyb true 893 894 895 896 897 See subsection 16 4 for further examples of the use of ignored keys Here we can see that a value is provided for keyb and yet we re ignoring the key However in practical applications it is often impossible to predict the set of keys among a set of them that may be executed at any time by th
41. and MtxkeysOparse is the list processor for the 1txkeys package It can process both arbitrary parser separated lists and key value pairs The flag which must lie in the range 0 3 determines the type of processing that is required The admissible values of flag and their meaning are given in Table 4 The macro ltxkeys parse loops over the given parser separated list and execute the user defined one parameter command ltxkeys do for every item in the list passing the item as an argument and preserving outer braces The default value of parser is comma The starred x variant of ltxkeys parse will expand listcmd once before commencing the loop Table 4 Flags for command ltxkeys parse Flag Meaning 0 list is assumed to be an ordinary list i e not a list of key value pairs it isn t normalized by ltxkeys parse prior to parsing 1 list is assumed to be an ordinary list i e not a list of key value pairs it is nor malized by ltxkeys parse prior to parsing 2 list is assumed to be a list of key value pairs it isn t normalized by ltxkeys parse prior to parsing 3 list is assumed to be a list of key value pairs it is normalized by ltxkeys parse prior to parsing Here are some points to note about the list processor ltxkeys parse a If an item contains parser it must be wrapped in curly braces when using N1txkeysOparse otherwise the elem
42. are many existing packages that rely on the xkeyval package and aliasing commands that are used by other packages can cause confusion 1 1 Motivation What are the raison d etre and origins of the 1txkeys package Well I decided to write this package as I grabbled with some practical problems of key parsing while developing version 1 5 0 of the xwatermark package The tasks proved more challenging than I had initially thought and despite its commendable and widely deployed features I found the xkeyval package inadequate in some respects As mentioned earlier all the functions of the 1txkeys package can be employed for general key management in IATEX beyond the xwatermark package Indeed the ltxkeys package can be used as a more robust replacement for the xkeyval package of course with modifications of names and some syntaxes The xkeyval package has been frozen since August 2008 2 Package options The package options are listed in Table 1 The package options can be passed via N ocumentclass RequirePackage or usepackage as follows Example Package options documentclass tracingkeys keyparser pathkeys article or usepackage tracingkeys keyparser 1txkeys They can also be passed via the command ltxkeys options 9 ltxkeys options tracingkeys false keyparser Table 1 Package options Option Default Meaning tracingkeys false The global boolean switch that
43. ault value of the first argument delim are the parameter delimiters keys are the keys to be defined for the command or environment defn is the replacement text of the command begdefn is the environment entry text and enddefn is the code to execute while exiting the environment The keys have the same syntax as they do for the command ltxkeys declarekeys subsec tion 3 8 The parameter delimiters delim given above in angled brackets have the syntax Parameter delimiters 614 1 delim1 2 delim2 9 delim9 where delimi and delim2 are the delimiters for the first and second parameters respectively etc Only the parameters with delimiters are to be specified in delim Examples are provided later In the ATEX newenvironment and renewenvironment commands with the syntax Macros newenvironment renewenvironment 615 newenvironment name narg dft begdefn enddefn 616 renewenvironment name narg dft begdefn enddefn the environment s parameters and or arguments aren t accessible in enddefn If the environment user wants to access the parameters in enddefn he has to save them while still in begdefn This isn t the case with the commands ltxkeysenv and reltxkeysenv for which the user can access the environment parameters while in enddefn To do this he should call the command 11 1txkeysrobust is an alias for ltxkeysprotected PAGE 36 or 66
44. ces of it being made active by any package is minimal If you have the chosen parser as literals in the callbacks of your keys they have to be enclosed in curly braces 1 3 The key setting commands are ltxkeys setkeys ltxkeys setrmkeys and ltxkeys setaliaskey If you must nest these commands beyond level 4 you have to raise the keydepthlimit as a package option The option keystacklimit is an alias for keydepthlimit 14 The use of an empty prefix will normally result from explicitly declaring the prefix as rather than leaving it undeclared Undeclared prefixes assume the default value of KV An empty family will result from submitting the family as empty balanced curly braces If keys lack prefix and or family there is a strong risk of confusing key macros functions For example without a prefix and or family a key named width will have a key macro defined as Width which portents sufficient danger Defining keys 3 1 Defining only definable keys If the package option tracingkeys is enabled i e turned true the user can see in the transcript file the existing keys that he has redefined with the ltxkeys xxxkey variants of the key defining commands which redefine existing keys without any default warning or error The log file messages being referred to here will be highlighted with the warning sign This is always desirable in the preproduction stages of your project However instead of looking for these warni
45. d doesn t permit the patching of commands with nested parameters But since key macros may have nested parameters a new patching scheme is to be first explored PAGE 62 OF 66 The Itxkeys package 19th December 2011 18 2 Modifying the dependant keys of an existing style key ltxkeys adddepkeys pref fam H paren deps ltxkeys removedepkeys pref fam paren deps ltxkeys replacedepkeys pref fam paren olddeps newdeps Here paren is the parent key of dependants keys deps is the full specification of new or existing dependant keys as in subsection 3 4 with their default values and callbacks olddeps are the old dependants to replace with newdeps This would require patching macros of the form pref fam key dependants which might have nested parametered commands 18 3 Toggle and switch keys Introduce toggle keys and switch keys but in practice who needs them I would really need user views before implementing this feature Toggles and switches found in e g the catoptions package are more efficient than conventional booleans in the sense that each of them introduces and requires only one command while each native boolean defines and requires up to three commands However toggles and switches haven t yet made it into the popular imagination of TEX users 19 Version history The following change history highlights significant change
46. d x variant of ltxkeys savexfamilykeys will expand keylistcmd once before saving the xfamily keys The starred x variant of ltxkeys definexfamilykeys will define only defin able keys in the sense of newcommand keylist and keylistcmd have the same syntax as the last arguments of ltxkeys definekeys and ltxkeys declarekeys Syntax of keylist keytype keyname dft cbk another set of key attributes etc Here too keytype must be a member of the set ord cmd sty sty bool choice keyname is obviously the name of the key dft is the default value of the key and cbk is the callback of the key If the key is a style key you can add the attributes of the dependants after cbk see the syntaxes of the commands ltxkeys definekeys and ltxkeys declarekeys The mandatory identifier id for each list must be unique not withstanding the fact that the identifiers have their separate namespace If the xfamily keys are all of the same type i e only one of the types ord cmd sty sty bool choice you can specify keytype as an optional argument in parenthesis to the command ltxkeys savexfamilykeys The parenthesis can t appear with an empty content ltxkeys savexfamilykeys lt x1 gt ord keya paperwidth mylength 1 cmd keyb black def y 1 1 choice keyc left right center center def z 1 1 bool keyd true J 4 Now define the keys previously stored with the id no x1 4 Fo
47. d outside defn begdefn enddefn and the environment body 14 1 Final tokens of every environment t1 The commands pathkeysval ifpathkeysval ifpathkeysvalTF pathkeyskeyval ifpathkeyskeyval and ifpathkeyskeyvalTF are always available but they can be used only in the context of pathkeys section 16 PAGE 37 OF 66 The Itxkeys package 19th December 2011 The user can add some tokens to the very end of every subsequent environment by declaring those tokens in the macro ltxkeys everyeoe which by default contains only IXTEX s command ignorespacesafterend That is the 1txkeys package automatically issues Example ltxkeys everyeoe 628 ltxkeys everyeoe ignorespacesafterend It is important to note that new tokens are prepended and not appended to the internal hook that underlies ltxkeys everyeoe such that by default ignorespacesafterend always comes last in the list You can empty the list ltxkeys everyeoe by issuing ltxkeys everyeoe and rebuild it anew still by prepending elements to it ltxkeys everyeoe isn t actually a token list register but it behaves like one It is safe to issue ltxkeys everyeoe token and or ltxkeys everyeoe in the begdefn part of the key environment One of the examples in subsection 14 2 illustrates this point Note 14 1 The pointer schemes of subsection 4 4 are applicable to key commands and key envir onments The needvalue pointer is us
48. e 1 in the command 1ltxkeys declareoption or a similar command will be the value entered in the documentclass command for this key First the global options from documentclass will set local keys and afterwards the local options specified via usepackage RequirePackage or LoadClass will set local keys which could overwrite the previously set global options depending on the way the options sections are constructed 13 1 Hooks for before and after processing options New macros ltxkeys beforeprocessoptions ltxkeys afterprocessoptions 603 ltxkeys beforeprocessoptions code 604 ltxkeys afterprocessoptions code The macros ltxkeys beforeprocessoptions and ltxkeys afterprocessoptions can be used to process an arbitrary code given in code before and after ltxkeys processoptions has been executed The command ltxkeys afterprocessoptions is particularly useful when it is required to optionally load a package with the decision dependent on the state or outcome of an option in the current package For obvious reasons IATEX s options parser doesn t permit the loading of packages in the options section The command ltxkeys afterprocessoptions can be used to load packages after the current package s options have been processed Here is an example for optionally loading some packages at the end of the options section Example ltxkeys afterprocessoptions ltxkeys cmdkey KV fam mp keya C
49. e Define the keys only if they don t already exist 3 declareoptions Declare the given options whether or not they already exist 4 declareoptions Declare the options if they don t already exist 5 preset Preset the listed keys on the given path This actually means preparing the list of preset keys 6 preset Preset the listed keys saving the list globally 7 postset Post set the listed keys 8 postset Post set the listed keys saving the list globally Continued on next page 13 This might sound like pgf keys but the semantics syntaxes and the implementation here are all different from those of pgf keys 14 However in most of this manual only one path is used in the sample syntaxes and in the examples PAGE 44 OF 66 The Itxkeys package 19th December 2011 Continued from last page No Flag Meaning 9 set Set the listed keys 10 set Set the listed keys and save undefined keys in the list of remaining keys without raising errors 11 set Set the listed keys in all the given key prefixes and families save undefined keys in the list of remaining keys without raising errors 12 setrm Set the remaining keys 1 13 setrm Set the remaining keys and again save undefined keys in the revised list of remaining keys without raising errors 14 setrm Set the remainin
50. e user of the keys Therefore na keys are much more useful than the above example demonstratese Some of the commands associated with pathkeys are listed below The abbreviation pk means the full key path and key name all separated by forward slash New macros pathkeysval ifpathkeysval ifpathkeysvalTF etc 898 The following commands are expandable pathkeysval pk ifpathkeysval pk then else fi ifpathkeysvalTF pk true false 4 The following commands aren t expandable pathkeyskeyval pk ifpathkeyskeyval pk then else fi ifpathkeyskeyvalTF pk true false pathkeys storevalue pk cmd 899 900 901 902 903 904 905 906 PAGE 47 OF 66 The Itxkeys package 19th December 2011 The commands pathkeysval and pathkeyskeyval simply yield the current value of the key The commands ifpathkeysval and ifpathkeyskeyval which require then to form balanced conditionals test the current state of the boolean key pk in a TEX like syntax The commands ifpathkeysvalTF and ifpathkeyskeyvalTF also test the current state of the boolean key pk but return true or false in a IATEX syntax The command pathkeys storevalue stores the current value of key pk in the given command cmd Note 16 2 If called outside an assignment or document environment the macros pathkeysval and pathkeyskeyval can give no
51. e current key name and 4 or NCurrentVal for the value of the current key If CurrentVal contains undefined macros or active characters then attempt ing to print it may cause problems Therefore when making entries in the transcript file it will sometimes be preferable to use InnocentVal instead of CurrentVal However InnocentVal detokenizes the current key value and if the value is more than 20 characters gives only the first 20 characters of a key s value 8 Options are also keys but from the user s viewpoint there might be a need to treat options separately when dealing with unknown keys PAGE 27 OF 66 The Itxkeys package 19th December 2011 The following example provides an unknown key handler for two key prefixes KVA and KVB and two key families fami and fam2 ltxkeys unknownkeyhandler KVA KVB fam1 fam2 expandtwoargs in 3 myspecialkeys ifin 4 The reader may want to investigate what the parameter texts 1 and 1 below stand for see note 4 3 below ltxkeys ordkey 1 2 3 4 Ndef x 1 GHHBELxodtHET h else ltxmsg warn Unknown key 3 with value 4 in family 2 ignored ehd 4 ltxmsg warn Unknown key CurrentKey with value 4 InnocentVal in family CurrentFam ignored ehd fi 492 493 494 495 496 497 498 499 500 501 502 503 The macro
52. e epRIERAYR UO RIA 48 pointers e eR RUE see key pointers post setting keys cece i ae ns 24 presetting keyS eu dsl oisean revirreti 24 R recalling the list of handled keys 30 weltxkeysemd cocci oildei ced ee pnr cere ttd 36 weltxkeyseny 2 cil uscscd ce egere neiess 36 remaining keys isse 21 renewenvironment ee eee eee eee 36 reserving key family 080 30 19th December 2011 reserving key prefix sess 30 TMK SYS oe si vice esa ted de wea eELELE QUU E deanna 21 S saved value of key cece cece eee eee 24 WEAVOVEING Less cepbeee eee DE Ie feeds 23 setaliaskey see ltxkeys setaliaskey Setting keys ie dae eher rebas 20 Nsetvarvalue e liii meis ecc wed ewoiepia 43 style keys sty ee dee UPPER PPS T style keys sty mierss persernes 15 16 46 U Ao ST PAB EEEE E E E E 51 unknown key and option handlers 27 unknown key handler in pathkeys 48 Yusepath oc ions oprea neirt Eni seas ER Eae 51 Maerinpu bl ono tock nas anea a nade teenie ee ds ome 15 MBO Ung PEE 23 V n E MEE EAEE LEE A trad etos baat on X xfamily k6yS i 3 22 dtd la DA ttiki IT PAGE 66 or 66
53. e it is possible to access the parent key s current value with parentval Within dft and cbk of deps it is possible to refer to the parent key s callback with its full macro PAGE 7 OF 66 The Itxkeys package 19th December 2011 name i e pref fam key parentval is always available for use as the default value of dependant keys but it may be lost in the callbacks of dependant keys because a dependant key once defined may be set independent of and long after the parent key has been executed It is therefore more reliable to refer to the macro pref fam key value which is recorded for only the parent key of style keys and which holds the current user input for the parent key The macro pref fam key value is recorded only if it appears at least once in the attributes of dependant keys The macro pref fam key value has a more unique name than mp key but they always contain the same value of a style key As mentioned above if mp is not given the user input for a style key will be available in the macro style pref fam key instead of mp Key Note 3 1 1 in the callback of parent key refers to the current value of the parent key while 1 in the callback of any dependant key refers to the current value of that dependant key Here is an example that defines and sets all undefined dependants on the fly Examples ltxkeys stylekey ltxkeys stylekey KV fam m
54. ed in one of the examples in subsection 14 2 14 2 Examples of key command and environment Examples Key command 629 It is possible to use parameter delimiters as the following 630 nil and mil show 631 ltxkeysglobal ltxkeysrobust ltxkeyscmd cmdframebox 632 3 default lt 2 nil 3 mil gt keys defn 633 No parameter delimiters for the following 634 ltxkeysglobal ltxkeysrobust ltxkeyscmd cmdframebox 3 default 635 cmd width textwidth 636 cmd textcolor black 637 cmd framecolor red 638 cmd framerule 4pt 639 cmd framesep 4pt 640 bool putframe true 641 bool testbool true 642 HA 643 begingroup 644 fboxrule keyval framerule relax 645 fboxsep keyval framesep relax 646 ifkeyval putframe then 647 fcolorbox keyval framecolor gray 25 648 MEX 649 parbox keyval width 650 color keyval textcolor 651 Arg 1 1 652 Arg 2 2 653 Arg 3 3 654 655 ifkeyval putframe then fi 1 However you can t do ltxkeys everyeoe expandafter cmd because ltxkeys everyeoe isn t a token list register PAGE 38 OF 66 The Itxkeys package 19th December 2011 689 690 691 692 693 694 695 696 ifkeyvalTF testbool def x T def y F endgroup begin document cmdframebox Text 1 Text 2 text 3 Text 4 A width 5 textwidth framecolor cyan textcolor purple framerule 1pt framesep 10pt
55. ed when the master is set They have the following syntaxes New macros ltxkeys stylekey ltxkeys newstylekey ltxkeys stylekey pref fam mp key dft deps cbk ltxkeys stylekey pref fam mp key dft deps cbk ltxkeys newstylekey pref fam mp key dft deps cbk ltxkeys newstylekey pref fam mp key dft deps cbk 21 22 23 24 The dependants deps have the syntax Dependant keys syntax keytype keyname dft cbk another set of dependant etc 25 26 27 28 The default value dft and the callback cbk can be absent in the syntax of style keys keytype can be ord ordinary key cmd command key bool boolean key or choice choice key Dependant keys always share the same key prefix pref family fam and macro prefix mp with the parent key If mp is given the command mp key will hold the current user input for the parent key other wise the user input will be available in style pref fam key The macro pref fam key will always hold the callback cbk If the starred x variant is used all undefined dependants will be defined and set on the fly as the parent is being set If the starred x variant isn t used and undefined dependants occur then an error message will be flagged at the time the parent is being set Most of the tim
56. ember 2011 the fly Handled keys should be defined or added to using key prefix family and key names You can define or add to handled keys by the following command 526 ltxkeys handledkeys pref fam list where list is a comma separated list of key names This command can be issued more than once for the same key prefix pref and family fam since the content of list is usually merged with the existing list rather than being merely added or overwritten There is also New macro ltxkeys addhandledkeys 527 ltxkeys addhandledkeys pref fam list which is just an alias for ltxkeys handledkeys 528 ltxkeys handledkeys KVA KVB fam1 fam2 keya keyb keyc For a given key prefix pref and family fam you can recall the full list of handled keys set up earlier by ltxkeys handledkeys by the command List of handled keys 529 pref fam handledkeys You can remove handled keys from a given list of handled keys in a family by the following command 530 ltxkeys removehandledkeys pref fam list Rather than remove individual handled keys from a list you might prefer or need to simply undefine or emptify the entire list of handled keys in a family You can do these with the following commands New macros ltxkeys undefhandledkeys ltxkeys emptifyhandledkeys 531 ltxkeys undefhandledkeys pref fam 532 ltxkeys emptifyhandledkeys pref fam
57. ents may be mixed up during parsing The braces will persist thereafter but will of course be removed during printing if the items are printed PAGE 59 or 66 The Itxkeys package 19th December 2011 b White spaces before and after the list separator are always ignored by the normalizer called by ltxkeys parse If an item contains parser or starts with a space it must therefore be wrapped in curly braces before calling ltxkeys parse c Since when flag is 0 or 2 the command ltxkeys parse doesn t call the normalizer in this case it does preserve outer surrounding spaces in the entries Empty entries in list or listcmd will be processed by ltxkeys parse if the boolean if1txkeys useempty is true You may thus issue the command ltxkeys useemptytrue before calling ltxkeys parse The ability to parse empty entries is required by packages that use empty key prefixes and or families if1txkeys useempty is false by default d The command ltxkeys parse can be nested to any level and can be mixed with other looping macros e In the command ltxkeys parse it is always possible to break out of the loop prematurely at any level of nesting simply by issuing the command loopbreak Breaking an inner loop doesn t affect the continuation of the outer loop and vice versa f The argument of the one parameter command ltxkeys do can be passed to a multi parameter command or to a command that expects delimited arguments
58. er 7 The callbacks can also take the following form center ltxkeys cmdkey KV fam mp keyd def x 1 CIHEWEDHBEDHBHHET right let align flushright left let align flushleft edef userinput cpttrimspaces 1 justified let align relax J center def z 1 2 1 1 2 7 ltxkeys choicekeys KV fam mp keya savevalue needvalue keyb PAGE 12 OF 66 19th December 2011 The Itxkeys package 19th December 2011 134 val order 135 center ltxkeys cmdkey KV fam mp keyd usevalue keyb 136 def x 1 4881 41 81 137 right def y 1 1 1 1 138 left edef userinput cpttrimspaces 1 139 justified letcsntocs 1 align relax 140 center 141 def z 1 2 1 1 2 7 142 143 ltxkeys setkeys KV fam keyb center keyd The representations savevalue usevalue and needvalue are pointers see subsection 4 4 3 6 1 Choice keys that share the same attributes The commands ltxkeys choicekey and ltxkeys newchoicekey can be used to introduce choice keys keys that share the same path or bases key prefix key family and macro pre fix and callback cbk All the user has to do is to replace key in these commands with the comma separated list keys Some users might prefer to see these commands in their plural forms when defining several keys with the same attributes We have therefore provided the fo
59. eys see section 7 can t be initialized or launched 4 8 Launching keys New macro ltxkeys launchkeys ltxkeys launchkeys prefs fams curr ltxkeys launchkeys prefs fams curr ltxkeys launchkeys prefs fams curr ltxkeys launchkeys prefs fams curr This presets all keys defined in families fams with their default values it ignores keys listed in curr curr may be the list of key value pairs that the user wants to use as current values of keys Their keys are to be ignored when setting up defaults i e when initializing the family keys One major difference between ltxkeys launchkeys and ltxkeys initializekeys is that in ltxkeys launchkeys the key value pairs in curr are immediately set after the absent family keys i e those without current values are reinitialized Keys appearing in curr in the command ltxkeys launchkeys will be the na ignored keys for the command ltxkeys initializekeys Keys across multiple prefixes prefs and families fams can be launched at the same time but the user has to know what is he doing the keys might not have been defined across the given families or some keys might have been disabled in some and not all families The and variants of ltxkeys launchkeys have the same meaning as in ltxkeys setkeys section 4 The starred x variant will save all undefined keys with prefix pref and in family fam in the macro p
60. eys etc 448 ltxkeys presetkeys pref fam keys 449 ltxkeys presetkeys pref fam H keys 450 ltxkeys addpresetkeys pref fam keys 451 ltxkeys addpresetkeys pref fam H keys 452 ltxkeys removepresetkeys pref fam keys PAGE 24 OF 66 The Itxkeys package ltxkeys removepresetkeys pref fam keys ltxkeys undefpresetkeys pref fam ltxkeys undefpresetkeys pref fam ltxkeys postsetkeys pref fam keys ltxkeys postsetkeys pref fam keys ltxkeys addpostsetkeys pref fam keys ltxkeys addpostsetkeys pref fam keys ltxkeys removepostsetkeys pref fam keys ltxkeys removepostsetkeys pref fam keys ltxkeys undefpostsetkeys pref fam ltxkeys undefpostsetkeys pref fam The optional here as in many instances in the 1txkeys package means that the assignments would be done and the lists built globally rather than locally Presetting keys means these keys should be set before setting other keys in every run of the command ltxkeys setkeys for the given key prefix and family ltxkeys addpresetkeys is an alias for ltxkeys presetkeys and this helps explain that ltxkeys presetkeys is indeed a list merger Neither the command ltxkeys presetkeys nor ltxkeys postsetkeys set keys itself contrary to what the names might suggest Post setting keys means these keys
61. f elements to remove nr are comma and 1 respectively If at least one mem ber of sublist is found and removed from listcmd then the callback fd is returned and executed otherwise nf is returned Both fd and nf provide some fallback following the execution of ltxkeys removeelements The challenge to the user is to remember that the command ltxkeys removeelements requires these callbacks which may both be empty The starred x variant of ltxkeys removeelements will remove from listcmd all the members of sublist found irrespective of the value of nr The optional nr is therefore redundant when the starred x variant of ltxkeys removeelements is called Here sublist is simply parser separated Mlefkxxia b c d d e f cid 4 Remove at most 2 occurrences of c and d from xx ltxkeys removeelements 2 xx c d def x done def x nil found 4 Remove all occurrences of c and d from xx ltxkeys removeelements xx c d def x done def x nil found 17 14 Replace one or all occurrences of elements in a csv list New macro ltxkeys replaceelements 1220 ltxkeys replaceelements parser nr listcmd sublist fd 4 nf 1221 ltxkeys replaceelements parser nr listcmd sublist fd nf The command ltxkeys replaceelements replaces nr number of each element of sublist in listcmd The default values of the optional list
62. families pathkeys false Load the pathkeys package see section 16 Table 1 notes 1 1 The speed of compilation may be affected by this option but it is recommended at the pre production stages of developing keys The option provide some trace functionality and enables the user to among other things follow the progress of the IXTEX run and to see if a key has been defined and or set executed more than once in the current run The starred x variants of the commands ltxkeys definekeys and ltxkeys declarekeys will always flag an error if a key is being defined twice irrespective of the state of the package option tracingkeys The ltxkeys xxxkey variants unlike the ltxkeys newxxxkey variants of key defining commands don t have this facility and it may be desirable to know if and when an existing key is being redefined L2 Wherever the semicolon is indicated as a list parser in this guide it can be replaced by any user specified one character parser via the package option keyparser To avoid confusing the user supplied parser with internal parsers it is advisable to enclose the chosen character in curly braces The braces will be stripped off internally Please note that some of the characters that may be passed as a list parser may indeed be active be careful to make them innocent before using them as a list key parser My advice is that the user sticks with the semicolon as the key parser the chan
63. fer to see these commands in their plural forms when defining several options with the same callback we have provided the following aliases New macros ltxkeys declarecmdoptions ltxkeys declarebooloptions etc 581 ltxkeys declareordoptions pref lt fam gt option dft cbk 582 ltxkeys declarecmdoptions pref lt fam gt mp option dft cbk 583 ltxkeys declarebooloptions pref lt fam gt mp option dft cbk 584 ltxkeys declarechoiceoptions pref fam mp option bin alt 585 dft cbk Declaring all types of option with one command New macro ltxkeys declaremultitypeoptions 586 ltxkeys declaremultitypeoptions pref lt fam gt mp 587 keytype keyname dft cbk 588 another set of key attributes 589 etc 590 591 ltxkeys declaremultitypeoptions pref lt fam gt mp PAGE 33 OF 66 The Itxkeys package 19th December 2011 592 keytype keyname dft cbk 593 another set of key attributes 594 BUC 595 Here the key default value dft and callback cbk can be absent in all cases keytype may be any one of ford cmd sty sty bool choice The star x in sty has the same meaning as in ltxkeys stylekey above namely undefined dependants will be defined on the fly when the parent key is set The optional quantity mp is the macro prefix as in for example subsec tion 3 3 The synta
64. fine 16 4 Pathkeys as class or package options To use the command pathkeys for declaring class or package options the user should simply call pathkeys with the flag declareoptions or declareoptions for defining only unique options The flags executeoptions processoptions and processoptions can be used to execute and process options respectively In this respect although not necessary you may want to change the default or current path to reflect the class file or package name Example Declaring and processing options MProvidesPackage mypackage 2011 11 11 v0 1 My test package newpath mypath mypackage myfunc myfunckeys Declare three unique options pathkeys usepath mypath declareoptions cmd opt1 12cm def y 1 1lyy 1 bool opt2 true if pathkeysval usepath mypath opt2 then def x T else def x F fi ord opt3 zz def z 1 1zz 1 1143 1144 1145 1146 1147 1148 1149 1150 J Set up defaults for options opti and opt2 ignoring option opt3 pathkeys usepath mypath executeoptions opti 10cm opt2 true opt3 yy opt3 J Ignore opti when processing options pathkeys usepath mypath processoptions opt1 1156 1157 documentclass opt1i 2cm opt2 false article usepackage opt3 somevalue mypackage 17 Some miscellaneous commands Some of the macros used internally by the 1txkeys package are available to the user A few of them a
65. following example will add a b c to macro Wy 1202 ltxkeys declarelistparser doloop 1203 doloopfa b c cptaddtolist y 17 The use of empty key prefixes families and paths is in general not advisable 18 The catoptions package is loaded by the ltxkeys package The ltxtools base package provides the com mand ltsdeclarelistparser which works similar to the macro ltxkeys declarelistparser but has a dynamic expandable list normalizer for arbitrary list parsers separators PAGE 60 OF 66 The Itxkeys package 19th December 2011 1204 4 The following example will add d e to macro Vy and ignore f 1205 doloop d e listbreak f cptaddtolist y 1206 Nesting of the iterator is possible 1207 ltxkeys declarelistparser alistparser 1208 ltxkeys declarelistparser blistparser 1209 def do 1 1 1210 def do 1 1 blistparser x y z do 1211 edef x alistparser a b c do 1212 4 This gives x macro gt a xyz b xyz c xyzZ 17 13 Remove one or all occurrences of elements from a csv list New macro ltxkeys removeelements 1213 ltxkeys removeelements parser nr listcmd sublist fd nf 1214 ltxkeys removeelements parser nr listcmd sublist fd nf The command ltxkeys removeelements removes nr number of each element of sublist from listcmd The default values of the optional list parser and the optional maximum number o
66. g keys in all the given key prefixes and families save undefined keys in the revised list of remaining keys without raising er rors 14 15 executeoptions Execute the listed options 16 processoptions Process the listed options in the order in which they were declared and don t copy documentclass options 16 17 processoptions Process the listed options in the order in which they appear in the com mand usepackage and copy documentclass options 18 launch Launch the listed keys see subsection 4 8 19 store value Store the value of key in the given macro 20 print value Print the current value of key 21 add value Add the specified value to the current value of key 22 ifbool Test the state of a boolean key This returns true or false 23 ifdef Test if key is currently defined on any of the given comma separated mul tiple paths This returns true or false 24 ifkeyonpath Test if key is currently defined on any of the given comma separated mul tiple paths This returns true or false 25 disable Immediately disable the given keys 26 disable Disable the given keys at the hook AtBeginDocument and not immedi ately 26 27 key handler or handler Unknown key handler 28 option handler Unknown option handler see subsection 4 9
67. g options New macro ltxkeys processoptions 601 ltxkeys processoptions prefs lt fams gt na 602 ltxkeys processoptions prefs lt fams gt na The command ltxkeys processoptions processes the key value pairs passed by the user to the class or package The optional argument na can be used to specify keys that should be ignored The optional argument fams can be used to specify the families that have been used to define the keys The default value of fams is currname currext The package command ltxkeys processoptions doesn t protect expandable macros in the user inputs unless the 1txkeys package is loaded before documentclass in which case it is also possible to use the PAGE 34 OF 66 The Itxkeys package 19th December 2011 command XProcessOptions of the catoptions package When used in a class file the macro ltxkeys processoptions will ignore unknown keys or options This allows the user to use global options in the documentclass command which can be inherinted by packages loaded afterwards The starred x variant of ltxkeys processoptions works like the plain variant except that if the 1txkeys package is loaded after documentclass it also copies user input from the command documentclass When the user specifies an option in the documentclass which also exists in the local family or families of the package issuing ltxkeys processoptions the local key too will be set In this cas
68. gnore keyd in defining keys saved in al ltxkeys definexfamilykeys lt a1 gt KV fam mp keyd On setting keya keyb and keyc will be defined and initialized ltxkeys setkeys KV fam keya left 298 299 300 301 Here is a real life example that mimics some of the macros of the xwatermark package Examples xfamily keys 302 ltxkeys savexfamilykeys lt a1l gt 303 cmd width Ntextwidth 304 cmd textcolor black 305 cmd framecolor black 306 cmd framesep 3 pQ 307 cmd framerule 0 4 pQ 308 choice textalign 7 309 center code def mp textalign center 310 left code def mp textalign flushleft 311 right code def mp textalign flushright 312 center 313 bool framebox true 314 ord junkkey throwaway 315 316 Ignore keys framebox and junkkey when defining family ltxframebox 317 ltxkeys definexfamilykeys lt a1 gt KV 1txframebox mp framebox junkkey 318 Ignore key junkkey when defining family ltxminipage 319 ltxkeys definexfamilykeys lt a1 gt KV 1txminipage mp junkkey 320 No key is ignored when defining junkfamily 321 ltxkeys def inexfamilykeys lt a1 gt KVX junkfamily mp 322 newcommand 1txframebox 2 7 323 ltxkeys setkeys KV 1ltxframebox 1 7 324 begingroup 325 fboxsep mp framesep fboxrule mp framerule 326 cptdimdef mp boxwidth mp width 2 fboxsep 2 fbo
69. he test The default values of the optional list parser and the optional number of elements to find nr are comma and 1 respectively PAGE 57 OF 66 The Itxkeys package 19th December 2011 17 7 Is the number of elements from a sublist found in a tsv list gt n New macro ltxkeys ifintsvlistTF 1178 ltxkeys ifintsvlistTF nr sub main true false 1179 ltxkeys ifintsvlistTF nr sub main true false The command ltxkeys ifintsvlistTF checks if the number of elements of nonparser separated tsv list sub found in main is equal or greater than nr The argument main is the main list and sub is the sublist of test strings Normally sub will be a user input and main the list of nominations Neither main nor sub is expanded in the test If the test is true ltxkeys itemspresent returns all the elements found ltxkeys nritems returns the num ber of elements found and true is executed If the test fails ltxkeys itemspresent re turns empty ltxkeys nritems returns 1 and false is executed The starred x variant of ltxkeys ifintsvlistTF will turn both input and nominations to lowercase before the test Normally tsv matching requires that the test strings in sub are unique in the nominations main Some caution is therefore necessary when dealing with tsv lists 17 8 Is the number of elements in a csv list gt n or lt n New macro lt
70. he unknown option and its value to another class or package or to specify other actions In fact you can use 1 in this macro to represent the current key prefix 2 for the current family 3 for the current key name and 4 for the value of the current key The command ltxkeys unknownoptionhandler is equivalent to the starred x variant of ltxkeys declareoption Note 11 1 The starred x variant of ltxkeys declareoption differs from the starred form of IATEX s DeclareOption and the starred form of xkeyval package s DeclareOptionX Examples ltxkeys declareoption ltxkeys declareoption KV lt mypackage gt PackageWarning mypackage Unknown option CurrentKey with value InnocentVal ignored ltxkeys declareoption PassOptionsToClass 3 article ltxkeys unknownoptionhandler KV lt mypackage gt expandtwoargs in 3 KV mypackage handledkeys ifin The reader may want to investigate what the parameter texts 1 and 1 below stand for ltxkeys ordkey 1 2 3 4 def x 1 41 xx 133 else PassOptionsToClass 3 myclass fi PAGE 32 OF 66 The Itxkeys package 19th December 2011 See note 4 3 for the meaning of the parameter texts in this example The contents of the macro KV mypackage handledkeys are handled keys for key prefix KV and family fam See section 8 for the meaning of handled keys New macros ltxkeys declarecmdo
71. hen T else F fi pathkeys mypath add value keya def cmdb 1 1 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 Instead of defining your own commands like the above mypath you can use the following name spaced commands New macros newpath defpath changepath undefpath usepath newpath pathname path defpath pathname path changepath pathname path undefpath pathname usepath pathname 1005 1006 1007 1008 1009 PAGE 50 OF 66 The Itxkeys package 19th December 2011 These commands have their own separate namespace Here pathname is used after definition as an abbreviation for the full path path The command newpath creates pathname if it didn t already exist defpath creates pathname whether or not it exists changepath is equivalent to defpath undefpath undefines pathname and usepath expands pathname to its full meaning The macro usepath does accept as argument a comma separated list of pathnames When using the flag ifdef or ifkeyonpath if path or pathname is a comma separated list all the given paths are searched in determining if the key is defined see the following example Examples newpath usepath newpath path1 fam subfam subsubfam1 newpath path2 fam subfam subsubfa
72. i dft i and cbk i are key name key default value and key callback respectively for key i The optional namespace is the private namespace for the declared variables and is used to avoid clashes of control sequences The key default value dft and callback cbk are optional and may be missing in the mandatory argument of ltxkeys declarevariables Example ltxkeys declarevariables ltxkeys declarevariables nynamespace 7 vari default value1 def userinput 1 def cmd 1 1 No callback var2 default value2 No default value and no callback var3 835 836 837 838 839 840 setvarvalues mynamespace vari new valuei var2 new value2 edef x getvarvalue mynamespace vari 841 842 843 begin document getvarvalue mynamespace vari end document 844 845 846 The private namespace is optional but clashes of control sequences might occur Example ltxkeys declarevariables ltxkeys declarevariables vari default value1 def userinput 1 def cmd 1 1 No callback var2 default value2 No default value and no callback var3 847 848 849 850 851 852 setvarvalues vari new valuei var2 new value2 edef x getvarvalue var1 853 854 begin document getvarvalue vari end document 856 857 858 16 Pathkeys Let us start this section with a welcome message you don t ha
73. ite reentrance They normally would know if and when they call each other or if they re being called by some other keys Examples ltxkeys biboolkeys ltxkeys biboolkeys KV fam mp0 keya keyb true ifmp keya def x 1 1x 1x 1 fi HY ifmp keyb def y 1 1y 1ly 1 fi Hi latex error Invalid value string 1 for keya or keyb ehc 68 69 70 71 72 73 J 74 Choice keys The choice keys of the 1txkeys package differ from those of the xkeyval package in at least two respects namely the presence of the macro prefix for choice keys in the 1txkeys package and the introduction of the optional prefix New macros ltxkeys choicekey ltxkeys newchoicekey ltxkeys choicekey pref fam mp key bin alt dft cbk ltxkeys choicekey pref fam mp key bin alt dft cbk ltxkeys choicekey pref fam mp key bin alt dft cbk fn ltxkeys choicekey pref fam mp key bin alt dft cbk fn 75 76 TT 78 79 ltxkeys newchoicekey pref fam mp key bin alt dft cbk ltxkeys newchoicekey pref fam mp key bin alt dft cbk ltxkeys newchoicekey pre fam mp key bin alt dft cbk fn ltxkeys newchoicekey pre fam mp key bin alt dft cbk fn 80 81 82
74. ixes 380 ltxkeys setaliaskey key value PAGE 21 OF 66 The Itxkeys package 19th December 2011 Here value is optional if it is not given key will be set with the current value of its alias The command setaliaskey is a shortened variant of ltxkeys setaliaskey ltxkeys def inekeys KV fam mp0 A printsign true printmark true ltxkeys setaliaskey printsign false keya keyb star ltxkeys setaliaskey keya 381 382 383 384 385 F ltxkeys definekeys KV fam np 7 keya sun CheckUserInput 1 star sun moon ifinputvalid edef givenval userinput edef found ifcase order star or sun or moon fi else latex error Input 1 not valid ehd Ns keyb star ltxkeys setaliaskey keya 386 387 388 389 390 391 392 393 394 395 396 The boolean ifinputvalid associated with the command CheckUserInput is described in macro line 182 see also subsection 17 2 The example involving printsign and printmark is similar but not equivalent to the notion of biboolean keys Biboolean keys have equal symmetry i e they can call each other with equal propensity and they won t bomb out in an infinite reentrance This is not the case with aliased keys only slave alias can set or call master main key If they both call each other the user will be alerted to
75. key command keys boolean keys etc can be used as the keys for the new command or environment d With the prefixes ltxkeysglobal and ltxkeysprotected global and robust key com mands and environments can be defined in a manner that simulates TRX s global and e TRX s Nprotected e The exit code for the key environment can have access to the arguments of the environment unlike in IATEX s environment f Simple commands are provided for accessing the current values and in the case of boolean keys the current states of keys The specification of the mandatory arguments and any optional first argument for the key command and key environment has the same syntax as in IXTEX s newcommand and newenvironment The key command and key environment of the 1txkeys package have the syntaxes New macros ltxkeyscmd ltxkeysenv etc pref ltxkeyscmd cs narg dft lt delim gt keys defn pref reltxkeyscmd cs narg dft lt delim gt keys defn pref pref pref ltxkeysenv name narg dft lt delim gt keys begdefn enddefn pref reltxkeysenv name narg dft lt delim gt keys begdefn enddefn Here pref is the optional command prefix which may be either ltxkeysglobal for global commands or ltxkeysprotected for e TEX protected commands cs is the command name is the environment name narg is the number of parameters dft is the def
76. keysOsetkeys cece eee eee eee eee 21 itxkeys setriikeys ccc2ce0c c0cacen iess 21 ltxkeys storevalue cece eee eee eee 24 ltxkeys stripallouterbraces 62 ltxkeys stripallouterbracesincs 62 ltxkeys stripNouterbraces 62 ltxkeys stylekey cc cee cece e ee eee 7 ltxkeys stylekeys cc cece eee eee eee ee 9 ltxkeys trimepaces 2 dte 56 MtxkeysO trimspacesincs ssussss 56 ltxkeys undefhandledkeys 30 ltxkeys undefpostsetkeys 25 MtxkeysQundefpresetkeys sues 25 ltxkeys undefsavevaluekeys 23 ltxkeys unknownkeyhandler 27 ltxkeys unknownoptionhandler 2 92 ltxkeys unreservekeyfamily 3l MtxkeysCunreservekeyprefix 31 ltxkeys unreservemacroprefix 31 WEG Shey Sem 2 nizesie Ret nen cates dpe be alas 36 VIEXKYSeDW l l elece erpeurebzevdacerembe rice 36 NIG RRS DODSLL es sales cian snk m REDEUER ES UR 36 Xltzkeysprotsected lee enr tpeg 36 XIbxkevarODuS 2 ll Lo2Se ec ece meus Medes 36 M macro prefix is l WWE Rae pes dan kept y 6 N need value keys esae beer pud bon rop 23 Mnewenvironment ssssssseeee ee 36 big T ed AS 51 no nested NMsetaliaskey sssss 22 Anomigati HS 2 22 6 M ge ex PIT 43 15 non launch keysS
77. l fam subfam subsubfam keya then def x T else def x F fi 981 982 983 984 Its correct form is Example Forward slashes in key defaults and macros pathkeys fam subfam subsubfam define bool keya true ifpathkeysval fam subfam subsubfam keya then def x T else def x F fi 985 986 987 988 16 1 Shortened pathkeys commands As seen above the estate for deploying pathkeys can be large when compared with the amount of typing required for conventional keys presented in the previous chapters To reduce the estate the first line of thought is to store any long path in a macro and call the macro instead of the path The path is always fully expanded under safe actives The following example demonstrates this approach Examples Putting paths in macros def mypath fam subfam subsubfam pathkeys mypath define cmd xwidth tempdima def y 1 lyy 1 cmd keya def cmda 1 1 bool putframe true pathkeys famx subfamx fam subfam ifkeyonpath xwidth def x T def x F pathkeys famx subfamx mypath ifkeyonpath xwidth def x T def x F pathkeys mypath set putframe true pathkeys mypath ifdef xwidth def x T def x F pathkeys mypath print value xwidth z pt pathkeys storevalue mypath putframe cmd edef x if pathkeysvalTF mypath putframe T F edef x ifpathkeysval mypath putframe then T else F fi edef x ifpathkeysval mypath putframe t
78. llowing aliases without modifying the internal coding New macros ltxkeys choicekeys ltxkeys newchoicekeys MtxkeysOchoicekeys pref fam mp keys bin alt dft cbk ltxkeys choicekeys pref fam mp keys bin alt dft cbk ltxkeys choicekeys pre am mp keys bin alt dft cbk fn ltxkeys choicekeys pre am mp keys bin alt dft cbk fn ltxkeys newchoicekeys pref am mp keys bin alt dft cbk ltxkeys newchoicekeys pref fam mp keys bin alt dft cbk ltxkeys newchoicekeys pre am mp keys bin alt dft cbk fn ltxkeys newchoicekeys pref fam mp keys bin alt dft cbk fn 3 7 Defining boolean and command keys with one command In my personal experience boolean and command keys have been the most widely used types of key in the context of xkeyval package More than one boolean and command keys can be defined simultaneously by the following command ltxkeys definekeys pref fam mp 1 key dft cbk another set of key attributes etc J ltxkeys def inekeys pref fam mp key dft cbk another set of key attributes etc PAGE 13 OF 66 The Itxkeys package 19th December 2011 The default value df
79. m LICENSE 7 This work i e all the files in the 1txkeys manifest may be distributed and or modified under the conditions of the TEX Project Public License LPPL either version 1 3 of this license or any later version The LPPL maintenance status of this software is author maintained This software is provided as it is without warranty of any kind either expressed or implied including but not limited to the implied warranties of merchantability and fitness for a particular purpose MMXI SUMMARY The 1txkeys package provides facilities for creating and managing keys in the manner of the keyval and xkeyval packages but it is intended to be more robust and faster than these earlier packages Yet it comes with many new functions The ltxkeys Package A robust key parser Ahmed Musat 19th December 2011 Contents 1 Introduction 2 3 9 Need value keys 17 11A Motivation pce orrore 4 4 3 10 Cross family keys 17 2 Package options 4 4 Setting keys 20 4 1 Setting defined keys 20 3 Defining keys 5 4 2 Setting remaining keys 21 3 1 Defining only definable keys 5 4 3 Setting aliased keys 21 3 2 Ordinary keys 6 4 4 Using key pointers 22 3 2 1 Ordinary keys that share the 4 5 Accessing the saved value of a key 24 same attributes 6 4 6 Pre setting and post setting keys 24 3 8 Command keys 6
80. m2 pathkeys usepath pathi define cmd keya xx def cmda 1 1 bool keyb true 1010 1011 1012 1013 1014 1015 pathkeys usepath pathi path2 ifkeyonpath keya def x T def x F pathkeys storevalue usepath pathi keyb cmd edef x ifpathkeysvalTF usepath path1 keya T F 1016 1017 1018 Examples defpath usepath set setrm defpath path1 fam subfam subsubfam1 defpath path2 fam subfam subsubfam2 Define key1 on two paths pathkeys usepath path1 path2 define cmd key1 12cm def y 1 1yy 1 1019 1020 1021 1022 1023 I 4 Set keys on paths 1 and 2 and put undefined keys in the rm list 4 instead of raising errors pathkeys usepath path1 path2 set key1 10cm key2 true key3 xx 1024 1025 1026 1027 1028 J 4 Set rm keys and again put undefined keys in the rm list 4 instead of raising errors pathkeys usepath path1 path2 setrm 1029 1030 1031 1032 The following shortened counterparts of the pathkeys commands are provided see Table 3 The abbreviated commands are available only after the user has invoked pathkeys useshortcmds which expects no argument The command pathkeys useshortcmds has only local effect i e the abbreviations may be localized to a group The abbreviations are defined only if they re definable i e didn t exist before calling the command pathkeys useshortcmds Table
81. merule 1 5pt framecolor red textcolor magenta putframe true dh ifval putframe then fbox fi parbox tempb color val textcolor outer box endgraf kkaaadkk vspace 5mm begin testenv A fraclen 0 1cm framerule 3pt framecolor green textcolor cyan putframe true yh ifval putframe then fbox fi parbox tempb 7 color val textcolor inner box endgraf vspace 5mm bbbt th ifval putframe then fi end testenv ifval putframe then fi end testenv end document cmd width textwidth cmd textcolor black cmd framecolor black cmd framesep 3 pQ Examples Key command ltxkeyscmd myframebox 2 default text PAGE 41 OF 66 19th December 2011 The following example shows that in place of the functions val ifval ifvalTF keyval ifkeyval and ifkeyvalTF the user can access the values and states of keys by concatenating the command or environment name the sign and the name of the key This of course requires that has catcode 11 The Itxkeys package 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 cmd framerule 0 4 pQ The following is choice key textalign with default value center The code in the admissible values is op
82. nd mytilewallpaper 2 begingroup pathkeyscurrentpath wallpaper fam pathkeys set 1 pathkeysuseshortcmds edef ffileext ifpdf pdf else eps fit edef reserved a pkv inputpath edef reserved a expandafter ltxkeys stripallouterbraces expandafter reserved a 7 edef Ginput path ifcsnullTF reserved a reserved a cptdimdef tilewidth paperwidth pkv wpxoffset 2 pkv xtilenr cptdimdef tileheight paperheight pkv wpyoffset 2 pkv ytilenr cptdimdef tileY paperheight pkv wpyoffset tempcntb z cptwhilenum tempcntb lt pkv ytilenr do edef tileX pkv wpxoffset tempcnta z cptwhilenum tempcnta lt pkv xtilenr do PAGE 53 OF 66 The Itxkeys package 19th December 2011 1099 leavevmode killglue 1100 cptexpanded noexpand put tileX tileY noexpand includegraphics 1101 viewport pkv viewport height Ntileheight width tilewidth clip 1102 2 ffileext 1103 advance tempcnta ne 1104 cptdimadd tilex tilewidth 1105 TA 1106 advance tempcntb ne 1107 cptdimadd tileY tileheight 1108 Ix 1109 endgroup 1110 1111 makeatother 1112 begin document 1113 def wpspec viewport 20 21 590 400 xtilenr 4 ytilenr 4 1114 wpxoffset 2cm wpyoffset 2cm inputpath graphics comet1 1115 AtBeginShipout 1116 AtBeginShipoutUpperLeft 1117 ifnumoddTF thepage expandafter mytilewallpaper wpspec 1118 1119 x 1120 end d
83. ng messages in the log file the user can use the ltxkeys newxxxkey variants of the key defining commands to bar himself from redefining existing keys Subsequently we will mention the ltxkeys newxxxkey variants of key defining commands without necessarily explaining what they mean since their meaning is henceforth clear PAGE 5 OF 66 The Itxkeys package 19th December 2011 In the following syntactic quantities in square brackets e g yyy and those in parenthesis e g Cyyy are optional arguments 3 2 Ordinary keys New macros ltxkeys ordkey ltxkeys newordkey 10 ltxkeys ordkey pref fam key dft cbk nu ltxkeys newordkey pre am H key d t cbk These define a macro of the form pref fam key of one parameter that holds the key func tion callback cbk The default value for the key prefix pref is always KV as in the xkeyval package When key is used in a ltxkeys setkeys command see section 4 containing key value the macro pref fam key takes the value as its argument and is then executed The given argument or key value can be accessed in the key s callback cbk by using 1 inside the function The optional default value dft if available will be used by pref fam key when the user hasn t provided a value for the key at ltxkeys setkeys If dft was absent at key definition and the key user hasn t provided a value for the key an
84. nt of the command 1txkeys in is identical with I3TEX2e kernel s 2011 06 27 in The command in tests for the presence of teststr in str and returns the boolean ifin as iftrue or iffalse The starred x variant of ltxkeys in returns two LXTEX branches true and false On the other hand the command ltxkeys iffound requires the first argument to be delimited by Nin and the second argument by then 15 The functions val and order are user supplied macros 16 There is also ltxkeys commacheckchoice whose parser is implicitly comma and does not need to be given by the user PAGE 56 or 66 The Itxkeys package 19th December 2011 1171 ltxkeys iffound xx in aax then def x T else def x F fi Note 17 1 The command ltxkeys iffound trims leading and trailing spaces around the tokens teststr and str before the test The commands ltxkeys in and ltxkeys iffound aren t expandable 17 4 Does a given pattern exist in the meaning of a macro 1172 ltxkeys ifpattern teststr cmd true false The command ltxkeys ifpattern simply determines if the meaning of cmd contains teststr It returns true if teststr is found in the meaning of cmd and false otherwise 17 5 ifcase for arbitrary strings ltxkeys ifcase teststr case 1 cbk 1 case n cbk n true false ltxkeys findmatch teststr case 1 cbk 1 case n cbk n fn
85. o prefix and yields either iftrue or iffalse The command ifvalTF expects as argument a boolean key and yields one of two IATEX branches true or false The commands val ifval and ifvalTF can be used in expansion contexts including in csname endcsname but if their arguments aren t defined as keys they will return an un defined command either immediately or later On the hand their counterparts namely the commands keyval ifkeyval and ifkeyvalTF will first check that the key has been defined before attempting to obtain its current value or state This affects their expandability when a key is undefined My advice is that the user should always use keyval ifkeyval and ifkeyvalTF instead of val ifval and ifvalTF unless he is sure he hasn t committed any mistakes in key s name but he might be writing a package that contains these commands for the use of the TEX community Also here there is an advantage in using protected edef in place of edef some IXTEX commands are protected with protect The commands val Nifval Ni fvalTF keyval Nifkeyval and ifkeyvalTF like the command and environment keys are available in defn begdefn and enddefn These commands i e val ifval ifvalTF keyval ifkeyval and ifkeyvalTF are pushed on entry into defn or begdefn and they are popped on exit of defn or enddefn Unless they re defined elsewhere outside the 1txkeys package they re undefine
86. ocument 16 3 Nested pathkeys The command pathkeys can be nested as the following example shows Example Nested pathkeys def mypath fam subfam subsubfam pathkeys mypath define cmd xwidth tempdima def y 1 1lyy 1 The default not callback of keya is def cmda 1 1 The key has no callback cmd keya def cmda 1 1 The callback of keyb says if keyb is true define keyc bool keyb true pathkeys mypath ifbool keyb pathkeys mypath define cmd keyc xx def cmdc 1 1 1 37 M keyd has no callback pathkeys mypath define choice keyd yes no yes 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 pathkeys mypath set keyb true 1135 1136 Try to find out why the following produces an error 1137 def nypath fam subfam subsubfam 1138 pathkeys mypath define 1139 cmd keya keyadefault PAGE 54 OF 66 The Itxkeys package 19th December 2011 1140 pathkeys mypath define cmd keyb xx def cmdb 1 1 1141 1142 pathkeys mypath set keya bbb The reason is that keyb was defined when the default was being set up for keya after the definition of keya The second setting of keya prompts an error that keyb is being redefined Notice that keyb is to be defined uniquely by the flag define To avoid this type of error you may consider removing x from de
87. opath This can be issued in documentclass Nusepackage or ltxkeys options This might be too drastic for many users and uses Therefore the 1txkeys package also provides the following commands that can be used for selectively unreserving currently reserved key bases New macros ltxkeys unreservekeyprefix ltxkeys unreservekeyfamily etc 539 ltxkeys unreservekeyprefix list 540 ltxkeys unreservekeyprefix list 541 ltxkeys unreservekeyfamily list 542 ltxkeys unreservekeyfamily list 543 ltxkeys unreservemacroprefix list 544 ltxkeys unreservemacroprefix list The starred x variants of these commands will defer action to the end of the current package or class while the unstarred variants will undo the reservation immediately 10 Bad key names Some key names are indeed inadmissible The 1txkeys considers the following literals among others as inadmissible for key names Default bad key names 545 code ordkey cmdkey choicekey boolkey 546 handledkeys presetkeys postsetkeys executedkeys rmkeys 547 needvalue savevalue usevalue savevaluekeys needvaluekeys 548 xkeys bool boolean tog togg 549 toggle switch true false on 550 off count Skip For reasons of efficiency the 1txkeys package will attempt to catch bad key names only if the package option tracingkeys is enabled You can add to the list of invalid key names by the following command New macros ltxkeys badkeynames lt
88. or if appropriate use space Examples ltxkeys definekeys 172 The starred x variant defines new keys 173 ltxkeys definekeys KV fam mp 174 Command key with callback 175 keya keepbraced def x 1 1 1 1 176 Boolean key 177 keyb true def y 1 lyyy 1 178 Command key with no callback 179 keyc xxx 180 Choice like command key 181 keyd center NCheckUserInputiisti left right center 182 ifinputvalid 183 edef myval expandcsonce userinput 184 edef numberinlist number order 185 edef mychoices expandcsonce nominations 186 else 187 latex error Input 1 not valid ehd 188 fi 189 Boolean key with no callback PAGE 14 OF 66 The Itxkeys package 19th December 2011 190 keye false 191 In this example userinput corresponds to 1 order is the numerical order of the user input in nominations the list of valid values suggested at key definition time left right center in this example The boolean inputvalid is associated with the command CheckUserInput and is available to the user It is set true when the user input is valid and false otherwise The command CheckUserInput expects two arguments the user input and the list of nominations It doesn t expect two branches see subsection 17 2 3 8 Defining all types of key with one command New macro ltxkeys declarekeys ltxkeys declarekeys pref fam mp ke
89. ound in a csv list gt n 57 17 7 Is the number of elements from a sub 12 Executing options 34 list found in a tsv list gt n 58 13 Processing apeione 34 17 8 Is the number of elements in a csv list 13 1 Hooks for before and after pro Sie ees ae eee 9n eTO oo coron 35 17 9 What is the numerical order of an ele mentinacsvlist 58 14 Key commands and key environments 35 17 10List normalization 59 14 1 Final tokens of every environment 37 17 11Parsing arbitrary csv or kv list 59 14 2 Examples of key command and envir 17 12Expandable list parser 60 Omemb fc be A ds 38 17 13Remove one or all occurrences of ele ments from a csv list 61 15 Declaring variables 42 17 14Replace one or all occurrences of ele ments inacsvlist 61 16 Pathkeys 43 17 15Stripping outer braces 62 16 1 Shortened pathkeys commands 50 16 2 Default and current paths 52 18 To do list 62 16 3 Nested pathkeys 54 16 4 Pathkeys as class or package options 55 18 SUDAN ROY ERE tis e dd ne x 18 2 Modifying the dependant keys of an 17 Some miscellaneous commands 55 existing style key 63 17 1 Trimming leading and trailing spaces 55 18 3 Toggle and switch keys 63 17 2 Checking user inputs 56 17 3 Does a test string exist in a string 56 19 Version history 63 17 4 Does a given pattern exist in the meaning of a macro 57 Inde
90. p keya left CA 1 here refers to the value of the DEPENDANT key at the time it is being set Use parentkey and parentval 4 here to access the parent key name and its current value ord keyb right def y 1 1 1 4 The default of keyc is the current value of parent keya cmd keyc Nparentval 4 Because KV fam keya value appears below it will be saved when the parent key keya is being set otherwise it would be unavailable bool keyd true ifmp keyd edef x 1 1 KV fam keya value fi 1 here refers to the value of the PARENT key at the time it is being set def x 1 1xx 1xx Check the value of parent key ltxkeys checkchoice userinput order 1 left right center 7 latex error Invalid input 1 ehd yh 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 i 48 In this example userinput corresponds to 1 and order is the numerical order of the user input in the nominations left right center More about the commands ltxkeys checkchoice and NCheckUserInput can be found in subsection 17 2 You can try setting keya as follows to see what happens to keys keyb keyc and keyd 49 ltxkeys setkeys KV fam keya right The following will flag an error because right isn t in the list of nominations left right center 50 ltxkeys setkeys KV fam keya right PAGE 8 OF 66 The It
91. package pushing and popping functions together involve looping over the functions only once And unlike in the xkeyval package higher order functions are undefined as soon as they are no longer needed to avoid clogging up the stack No additional looping is required for this In setting keys the 1txkeys package loops over not only families as in the xkeyval package but also over key prefixes The same strategy applies when the 1txkeys package tries to establish if a key is defined or not While some user interfaces of the 1txkeys package are similar to those of the xkeyval package there are important differences in several areas of syntax semantics and internal implementation The 1txkeys package also provides additional facilities beyond the xkeyval package for defining and managing keys Several types of keys including ordinary keys command keys style keys choice keys boolean and biboolean keys can be efficiently created and managed In the 1txkeys package the notions of pre setting and post setting keys are similar to those of the xkeyval package But the 1txkeys package introduces additional concepts in this respect initialized and launched keys The latter are special preset keys The pointer system of the xkeyval package which was available only at key setting time is now available also at key definition time One more type of pointer needvalue has been introduced to require users of need value keys
92. parser and the optional maximum num ber of elements to replace nr are comma and 1 respectively If at least one member of sublist is found and replaced in listcmd then the callback fd is returned and executed otherwise nf is returned Both fd and nf provide some fallback following the execution of ltxkeys replaceelements The challenge to the user is to remember that the command ltxkeys replaceelements requires these callbacks which may both be empty The starred x PAGE 61 OF 66 The Itxkeys package 19th December 2011 variant of ltxkeys replaceelements will replace in listcmd all the members of sublist found irrespective of the value of nr The optional nr is therefore redundant when the starred x variant of ltxkeys replaceelements is used Here the syntax of sublist is as follows a 1222 old 1 new 1 parser parser old n new n where old i is the element to be replaced and new i is its replacement def xxfa b c d d e f c d 4 Replace at most 2 occurrences of 4 respectively ltxkeys replaceelements 2 xx c s d t def x done def x nil found Replace all occurrences of c and d in xx with s and t ltxkeys replaceelements xx c s d t def x done def x nil found co and d in Nxx with s and St 17 15 Stripping outer braces The list and key parsers of the
93. ption ltxkeys declarebooloption etc 572 ltxkeys declareordoption pref lt fam gt option dft cbk 573 ltxkeys declarecmdoption pref lt fam gt mp option dft cbk 574 ltxkeys declarebooloption pref lt fam gt mp option dft cbk 575 ltxkeys declarechoiceoption pref fam mp option bin alt 576 dft cbk These are the equivalents of the macros ltxkeys ordkey ltxkeys cmdkey ltxkeys boolkey and ltxkeys choicekey respectively but now the family fam is optional as is pref and when specified must be given in angled brackets The default family name for these new com mands is currname currext i e the current style or class filename and filename extension ltxkeys declareordoption is equivalent to the unstarred variant of ltxkeys declareoption See the choice keys in subsection 3 6 for the meaning of bin and alt associated with the command ltxkeys declarechoiceoption 11 1 Options that share the same attributes The commands Macros 577 ltxkeys declareordoption 578 ltxkeys declarecmdoption 579 ltxkeys declarebooloption 580 ltxkeys declarechoiceoption can each be used to introduce several options that share the same path or bases option prefix option family and macro prefix and callback cbk All that is needed is to replace option in these commands with the comma separated list options Because some users might pre
94. r returns 1 which can be used for taking further decisions PAGE 58 OF 66 The Itxkeys package 19th December 2011 17 10 List normalization New macros ltxkeys commanormalize ltxkeys kvnormalize ltxkeys commanormalize list cmd ltxkeys commanormalizeset list 1 cmd 1 List n cmd n ltxkeys kvnormalize list cmd ltxkeys kvnormalizeset list 1 cmd 1 list n cmd n 1185 1186 1187 1188 These commands will normalize the comma separated list or list i and return the result in cmd or cmd i For the command ltxkeys kvnormalize list is assumed to be a list of key value pairs Normalization implies changing the category codes of all the active commas to their standard values as well as trimming leading and trailing spaces around the elements of the list and removing consecutive multiple commas Thus empty entries that are not enforced by curly braces are removed Besides dealing with multiple commas and the spaces between entries the command ltxkeys kvnormalize removes spaces between keys and the equality sign and multiple equality signs are made only one Further the category codes of comma and the equality sign are made normal throughout the list 17 11 Parsing arbitrary csv or kv list New macro ltxkeys parse 1189 ltxkeys parse flag parser list 1190 ltxkeys parse flag parser listcmd The unexpandable comm
95. r now don t define keys keyb and keyc MtxkeysOdefinexfamilykeys x1 KV fam mp0 keyb keyc Once defined the keys can be executed separately ltxkeys setkeys KV fam keya 5 hsize keyd false show ifmp keyd 4 Now define the keys previously stored with the id no x1 for 4 another family This time we don t want to define key keyb MtxkeysOdefinexfamilykeys x1 KVA fama mpa keyb 4 You can save and define xfamily keys of only one key type command keys in the following example ltxkeys savexfamilykeys lt x1 gt cmd 7 keya paperwidth keyb blue def x 1 1x 1 Define the saved keys and ignore none of them MtxkeysOdefinexfamilykeys x1 KV fam mp PAGE 18 OF 66 19th December 2011 The Itxkeys package 19th December 2011 287 ltxkeys setkeys KV fam keya 5 hsize keyb red 4 keya and keyd are starred style keys but keyd has no dependants ltxkeys savexfamilykeys lt al gt sty keya center code def xx 1 1xx 1 ord gt needvalue keyb gt parentval gt edef yy 1 1yy unexpanded 1 4 The braces around center the default value of keyc 4 will be preserved in parsing cmd gt keyc gt center The braces around the callback of keyd will be preserved keyd red code def x color 1 print aaa 288 289 290 291 292 293 294 295 296 297 I
96. rame 4 Unknown key handler pathkeys fam subfam subsubfam key handler 1 is the key s main path 2 is the subpaths combined 4 3 is the key name and 4 is the current value of the key ltxkeys warn Unknown key 3 with value 4 ignored 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 y pathkeys fam subfam subsubfam disable keya keyb keyc 930 931 Examples Pathkeys 932 pathkeys KV frame framebox define 933 cmd width textwidth def x 1 1xx 1 934 cmd textcolor black 935 cmd framecolor black 936 cmd framesep 3 pQ 937 cmd framerule 0 4 pQ 938 cmd cornersize 20 pQ 939 choice textalign 7 PAGE 48 OF 66 The Itxkeys package 940 941 942 943 944 945 946 947 969 970 971 972 973 974 975 976 977 978 979 980 center code def ttextalign center left code def ttextalign flushleft right code def ttextalign flushright center bool putframe true cmd arga cmd argb i newcommand myframebox 1 7 4 Use set or launch here but they don t have the same meaning pathkeys KV frame framebox set 1 begingroup fboxsep pathkeysval KV frame framebox framesep fboxrule pathkeysval KV frame framebox framer
97. re described below 17 1 Trimming leading and trailing spaces New macros ltxkeys trimspaces ltxkeys trimspacesincs 1160 ltxkeys trimspaces token cs 1161 ltxkeys trimspacesincs cs PAGE 55 OF 66 The Itxkeys package 19th December 2011 The command ltxkeys trimspaces trims i e removes the leading and trailing spaces around token and returns the result in the macro cs Forced i e explicit leading and trailing spaces around token are removed unless they are enclosed in braces The command ltxkeys trimspacesincs trims the leading and trailing spaces around the token in the macro cs and returns the result in cs 17 2 Checking user inputs New macros ltxkeys checkchoice ltxkeys checkinput CheckUserInput 1162 ltxkeys checkchoice parser val order f input H nomin H true 1163 ltxkeys checkchoice parser val order input H nomin H true 1164 ltxkeys checkchoice parser val order input nomin true false 1165 ltxkeys checkchoice parser val order input nomin true false 1166 ltxkeys checkinput input nomin true false 1167 CheckUserInput input nomin The command ltxkeys checkchoice is a re implementation of xkeyval package s command XKV checkchoice so as to accept arbitrary list parser parser and for more robustness It checks the user input input against the list of nominations
98. ref fam rmkeys to be set later perhaps with the command ltxkeys setrmkeys PAGE 26 OF 66 The Itxkeys package 19th December 2011 The plus variant will search in all the prefixes in prefs and all families in fams for a key before logging the key in pref fam rmkeys if the x variant is the one used or reporting it as undefined 4 8 1 Non initialize and non launch keys Listing all the keys that shouldn t be reinitialized by ltxkeys initializekeys in the na list every time ltxkeys initializekeys is called can sometimes be inconvenient especially when dealing with a large number of keys Perhaps even more important is the fact that sometimes you don t want some of the keys in a family to be reinitialized even though they are absent keys i e they aren t listed as current keys meaning that they aren t in the current key value list submitted to ltxkeys launchkeys This might be the case with package and class options The command ltxkeys nonlaunchkeys provides a convenient means for listing the non reinitializing keys once and for all If there are keys in a family that shouldn t be reinitial ized launched with other keys in the same family during any call to ltxkeys launchkeys or ltxkeys initializekeys they can be listed in the ltxkeys nonlaunchkeys command 489 ltxkeys nonlaunchkeys prefs ams H keys Keys across multiple prefixes and families can be submitted to
99. s concept New macros ltxkeys optionkeys ltxkeys nonoptionkeys ltxkeys optionkeys pref fam keys ltxkeys optionkeys pref fam keys ltxkeys nonoptionkeys pref fam keys Here keys is a comma separated list of keys to be made option or non option keys Keys listed in ltxkeys optionkeys can appear only in arguments of documentclass RequirePackage or usepackage while keys listed in ltxkeys nonoptionkeys can t appear in these macros The starred x variant of ltxkeys optionkeys is equivalent to ltxkeys nonoptionkeys Only defined keys may appear in ltxkeys optionkeys and ltxkeys nonoptionkeys ltxkeys makeoptionkeys pref fam ltxkeys makeoptionkeys pref fam ltxkeys makenonoptionkeys pref fam The command ltxkeys makeoptionkeys makes all the keys with prefix pref and in family fam options keys The command ltxkeys makenonoptionkeys does the reverse i e makes the keys non option keys The starred x variant of ltxkeys makeoptionkeys is equivalent to ltxkeys makenonoptionkeys 8 Handled keys As mentioned in subsection 4 9 handled keys are keys defined in a macro that is key prefix and key family dependent They are defined as a list in a macro so that they can be used for future applications such as deciding if a dependant key of a style key should be defined or redefined on PAGE 29 OF 66 The Itxkeys package 19th Dec
100. s setkeys pref fam na keyval ltxkeys setkeys pref fam na keyval PAGE 20 OF 66 The Itxkeys package 19th December 2011 373 ltxkeys setkeys prefs fams na keyval 374 ltxkeys setkeys prefs fams na keyval Here prefs fams and keyval are comma separated list of key prefixes families and key value pairs respectively Keys listed in the comma separated list na are ignored The starred x variant will save all undefined keys with prefix pref and in family fam in the macro pref fam rmkeys to be set later perhaps with ltxkeys setrmkeys The plus variant will search in all the prefixes in prefs and all families in fams for a key before logging the key in pref fam rmkeys if the x variant is used or reporting it as undefined To avoid infinite re entrance of ltxkeys setkeys and the consequent bombing out of the com mand the package option keydepthlimit is introduced Its default value is 4 meaning that ltxkeys setkeys can t ordinarily be nested beyond level 4 If you must nest ltxkeys setkeys beyond this level an unlikely need you can raise the keydepthlimit as a package option via usepackage or if catoptions package is loaded before documentclass via documentclass For example Setting keydepthlimit 375 usepackage keydepthlimit 6 1txkeys The more appropriate name keystacklimit is an alias for keydepthlimit
101. s that affect user utilities and interfaces changes of technical nature are not documented in this section The star sign on the right hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide Version 0 0 3 2011 12 17 More flags preset postset setrm etc have been introduced for pathkeys section 16 Version 0 0 2 2011 09 01 Pathkeys introduced 2 020 2420 dus ek 9 RR RR 3 EUR RA section 16 User guide completed ern Version 0 0 1 2011 07 30 First public release 3 2222 ko ko RR 8v gh ROUES ee URS ee RO Pob e OE Ew s PAGE 63 or 66 The Itxkeys package 19th December 2011 INDEX Index numbers refer to page numbers Symbols MODE EIE see code Lp Cm 11 16 19 A after processoptions 000 35 aliased keys isse ede mira nier 21 B before processoptions ss esses 35 biboolean keys e rer e POT ER 10 boolean keys bool sssssssss 9 C Nehangpepndbi nor cseescee iad Mas PF cea ee OE 51 CheckUserInput 0 00 42 cc eee ecce ee 15 56 CHOICE key8 eee PRI e ede Adee aE Minputvalid scs essccnctcete cs dee ER chante 15 nominations eese 15 NOMINATIONS eoe eter dave DUE e Hae 1l choice keys choice 0 eee eee eee 10 Class OptionS i lesu mele AREIS RIS canes 32 Command Key8 ccRESfUbek aieri HIND nae 35 command keys cmd
102. t can be absent in the case of command keys and the callback cbk can be absent for the two types of key Boolean keys must however have default values true false to be distinguishable from command keys The equality sign that separates the key name from the default value can be replaced with forward slash That is the following syntax is also permitted ltxkeys definekeys pref fam mp 1 key df t cbk another set of key attributes etc J ltxkeys definekeys pref fam mp key df t cbk another set of key attributes etc You can use the command CheckUserInput in cbk to indirectly introduce choice keys as com mand keys see example below Ordinary keys and conventional choice keys can t be introduced directly by this command use the command ltxkeys declarekeys instead The starred x variant of ltxkeys definekeys can be used to define non existing boolean and command keys in the sense of newcommand Note 3 3 Keys defined by ltxkeys definekeys are automatically set initialized instantly to provide default values for immediate use Boolean keys are preset with value false so that they aren t turned true prematurely Note 3 4 In ltxkeys definekeys and ltxkeys declarekeys every line is assumed to end with a comment sign This is to be specially noted if a space is desired at the end of line You can insert such a space with a comment sign
103. t 2 nil 3 Qmil gt defn 4 No parameter delimiters for the following ltxkeysglobal ltxkeysrobust ltxkeysenv envframebox 3 default cmd width textwidth def xx 1 1 cmd textcolor black cmd framerule 4pt ord framecolor brown bool putframe true 4 begingroup fboxrule val framerule relax ifval putframe then fcolorbox val framecolor gray 25 fi parbox val width Arg 1 1 Arg 2 textcolor val textcolor 2 Arg 3 3 th ifval putframe then fi endgroup M edef firstarg envarg 1 def yy 1 1 begin document begin envframebox Text 1 Text 2 test text 2 Text 3 width 5 textwidth textcolor purple framerule 1pt putframe true 733 734 735 736 737 end envframebox end document Examples Nested key environments 742 def testenv 743 reltxkeysenv testenv A 744 The y below is just a test 745 cmd fraclen 0 1cm def y 1 1yyy 1 746 cmd framerule 4pt 747 cmd framecolor blue 748 cmd textcolor black PAGE 40 OF 66 The Itxkeys package T79 780 TEL 782 783 784 785 786 787 790 TOT 792 793 bool putframe true 0 NcptdimdefNtempbi 5Ntextwidth Nval fraclen Ncurrentgrouplevel noindent endgraf fboxrule val framerule relax color val framecolor begin document begin testenv A fraclen 0 1cm fra
104. the fact that there is an infinite reentrance of keys The notion of slave and master used in the 1txkeys package may be counterintuitive but in reality it is quite logical Schemes like the following are disallowed to avoid back linking of ltxkeys setaliaskey The package will flag an error if something like the following occurs Examples Illegal nested ltxkeys setaliaskey ltxkeys ordkey KV fam keya true setaliaskey keyb ltxkeys ordkey KV fam keyb true setaliaskey keya ltxkeys setkeys KV fam keya 397 398 399 4 4 Using key pointers The savevalue and usevalue pointers of the xkeyval package are still available at key set ting time but with increased robustness and optimization Curly braces in values are preserved throughout and instead of saving the value of each key tagged with savevalue in a separate macro we save all such keys and their values in only one macro for each combination of pref and fam and use a fast search technique to find the values when they are later needed by any key tagged with usevalue The pointer needvalue is a new type It can be used by any key author to prompt the user of the key to always supply a value for the key The pointers savevalue usevalue and needvalue can all be called when defining keys The pointer usevalue will however be ignored when defining keys i e if present it s simply dropped If required
105. tional but not the forward slash choice textalign 7 center code def ttextalign center left code def ttextalign flushleft right code def ttextalign flushright center bool putframe true d begingroup fboxsep myframebox framesep fboxrule myframebox framerule relax cptdimdef myframebox boxwidth nyframebox width 2 fboxsep 2 fboxrule noindent begin 1lrbox tempboxa begin minipage c height s myframebox boxwidth killglue begin ttextalign textcolor myframebox textcolor Arg 1 1 endgraf Arg 2 2 end ttextalign end minipage end lrbox killglue color mnyframebox framecolor ifmyframebox putframe fbox fi usebox tempboxa ifmyframebox putframe fi endgroup begin document myframebox Text 1 Test text 2 test text 2 framerule 2pt framecolor blue textcolor purple putframe true textalign right end document 15 Declaring variables Sometimes keys are used simply to save values for later use This can be achieved easily by using the command ltxkeys declarevariables New macro ltxkeys declarevariables setvarvalues getvarvalue ltxkeys declarevariables namespace key 1 dft 1 cbk 1 key n dft n cbk n setvarvalues namespace key value pairs getvarvalue namespace key PAGE 42 OF 66 19th December 2011 The Itxkeys package 19th December 2011 Here key
106. ule relax cptdimdef boxwidtha pathkeysval KV frame framebox width 2 fboxsep 2 fboxrule yh noindent begin 1rbox tempboxa begin minipage c height s boxwidtha killglue begin ttextalign textcolor pathkeysval KV frame framebox textcolor Arg 1 pathkeysval KV frame framebox arga endgraf Arg 2 pathkeysval KV frame framebox argb yh end ttextalign end minipage end 1rbox killglue color pathkeysval KV frame framebox framecolor ifpathkeysval KV frame framebox putframe then ovalbox fi usebox tempboxa ifpathkeysval KV frame framebox putframe then fi endgroup begin document Wnyframebox arga Text 1 argb Test text 2 test text 2 framerule 2pt framecolor blue textcolor purple putframe true textalign right end document Note 16 3 When using pathkeys and in general the commands ltxkeys definekeys and ltxkeys declarekeys there is a potential problem in deploying forward slashes in key de faults and macros without enclosing those slashes in curly braces They will confuse the parser Several solutions exist including tweaking the relevant internal parser but I haven t decided on the optimal solution to this possibility For example the following will fail PAGE 49 OF 66 19th December 2011 The Itxkeys package 19th December 2011 Example Forward slashes in key defaults and macros pathkeys fam subfam subsubfam define bool keya true ifpathkeysva
107. using the tools of this section Even if not all the cross family keys are needed in all the families to which they may belong there are still advantages in using this type of keys when some of the keys cut across families Cross family keys are automatically initialized after being defined as we saw in the case of the commands ltxkeys definekeys and ltxkeys declarekeys New macros ltxkeys savexfamilykeys ltxkeys definexfamilykeys 255 ltxkeys savexfamilykeys lt id gt keylist 256 ltxkeys savexfamilykeys lt id gt keylistcmd 257 ltxkeys savexfamilykeys lt id gt keytype keylist 258 ltxkeys savexfamilykeys lt id gt keytype keylistcmd 259 ltxkeys def inexfamilykeys lt id gt pref fam mp na 260 ltxkeys def inexfamilykeys lt id gt pref fam mp na Here id is the mandatory identifier of the key list keylist pref is the key prefix fam the key family mp is the macro prefix and na is the list of keys belonging to keylist that shouldn t be presently defined and initialized The na can be empty but it must always be there as a mandatory argument So where you put the key list in the commands ltxkeys definekeys and ltxkeys declarekeys is where you now have to locate na For any use of the command PAGE 17 OF 66 The Itxkeys package 262 263 ltxkeys definexfamilykeys we expect the na to be far less than the remaining keys The starre
108. value list Like the above layout option each key of amloadmodules may have a value representing module options that is itself a comma separated key value list Well the type of robustness described here isn t actually difficult to implement within the xkeyval package This is indeed what the keyreader package does it patches some commands of the xkeyval package to achieve this robustness That said we have to indicate that the ltxkeys package implements this robustness intrinsically and it has many more features than the xkeyval and keyreader packages The 1txkeys package is faster than the xkeyval package mainly because it avoids character wise parsing of key values which is called selective sanitization by the xkeyval package Moreover it is faster to normalize a comma separated or key value list than trim leading and trailing spaces of each element of the list as the xkeyval package does since not all the elements of the list will normally have leading and trailing spaces In fact the chances are that only less than 50 percent of the elements of the list will have such spaces As another example of optimization anyone familiar with the implementation of the xkeyval package would have noticed that the macro XKV srstate which in order to allow setkeys to be re entrant pushes and pops the states of some important functions in the package loops over all the functions both when pushing and popping In the 1txkeys
109. ve to repeatedly type in long key paths and commands when using pathkeys There is plenty of help ahead on how to reduce estate when using pathkeys The pathkeys package can be loaded on its own via RequirePackage or usepackage or as an option to the 1txkeys package see Table 1 All the options listed in Table 1 are accepted by the pathkeys package They are all passed on to 1txkeys package except pathkeys that is simply ignored by pathkeys package PAGE 43 OF 66 The Itxkeys package 19th December 2011 Pathkeys are keys with a tree or directory structure When defining and setting pathkeys the full key path is usually required This is also the case when seeking the current value or state of a key When using pathkeys the user is relieved of the need to known and remember where the optional arguments have to be placed in calls to macros And like the commands ltxkeys definekeys and ltxkeys declarekeys pathkeys are automatically initialized after definition i e they are automatically set with their default values The command for defining and setting pathkeys is pathkeys which has the following syntax The same command is used for several other tasks related to pathkeys The flag entry in the argument of pathkeys determines the action that the command is expected to take 859 pathkeys paths flag attrib In the argument of command pathkeys paths has the syntax 860 maini subi subsubi
110. x 1044 pathkeys launch 1 1045 begingroup 1046 pathkeysGuseshortcmds 1047 fboxsep pkv framesep fboxrule pkv framerule relax 1048 cptdimdef boxwidtha pkv width 2 fboxsep 2 fboxrule 7 1049 noindent begin 1rbox tempboxa PAGE 52 OF 66 The Itxkeys package 19th December 2011 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 begin minipage c height s boxwidtha killglue begin ttextalign textcolor pkv textcolor Arg 1 pkvf arga endgraf Arg 2 pkv argb end ttextalign end minipage end 1rbox killglue color pkv framecolor ifpkv putframe then ovalbox fi usebox tempboxa ifpkv putframe then fi endgroup begin document Wnyframebox arga Text 1 argb Test text 2 test text 2 framerule 2pt framecolor blue textcolor purple putframe true textalign right end document Examples Tiling with pathkeys documentclass article usepackage atbegshi picture graphicx ifpdf usepackage pathkeys makeatletter pathkeys wallpaper fam define cmd viewport 00 00 100 100 xtilenr 2 ytilenr 2 wpxoffset Opt wpyoffset Opt inputpath newcomma
111. x 64 Introduction T HE LTXKEYS PACKAGE provides facilities for creating and managing keys in the manner of the keyval and xkeyval packages but it is intended to be more robust and faster than these earlier packages Its robustness emanates from inter alia its ability to preserve braces in key values throughout parsing The need to preserve braces in key values without expecting the user to double braces emerges often in parsing keys This is the case in e g the xwatermark package but consider also the possibility of passing all the following options to a package at once where layout is a package or class option or key Braced option values Npkgoptionsi opti vali opt2 val2 layout left 3cm right 3cm top 2 5cm bottom 2 5cm include true i As a practical example the amtools package has the command amloadmodules with the syntax 1Tt should be noted that if a value of the demonstrative option layout is expandable then the option can t be passed by documentclass without preloading a robust options parser like kvoptions patch xkvltxp catoptions or ltxkeys package In fact IATEX s native options processor can t handle options with values The ltxkeys package unlike the xkeyval package can be loaded before documentclass PAGE 2 OF 66 The Itxkeys package 19th December 2011 Braced key values 5 amloadmodules base modules where modules is a comma separated key
112. x for the command ltxkeys declaremultitypeoptions is identical to that of ltxkeys declarekeys except for the following differences For ltxkeys declarekeys the fam ily is mandatory and must be given in curly braces while for ltxkeys declaremultitypeoptions the family is optional with the default value of currname currext i e the name of the class file or package and its file extension For ltxkeys declaremultitypeoptions the op tional family is expected to be given in angled brackets The starred x variant of the command ltxkeys declaremultitypeoptions defines only undefined options An alias for the long com mand ltxkeys declaremultitypeoptions is Ndeclaremultitypeoptions Example ltxkeys declaremultitypeoptions declaremultitypeoptions KV lt fam gt np cmd option1 xx def x 1 1xx 1 bool option2 true 596 597 598 599 i 42 Executing options 600 ltxkeys executeoptions prefs lt fams gt na keyval This executes sets the key value pairs given in keyval The optional na specifies the list of keys without values to be ignored prefs is the list of prefixes for the keys and the optional fams signifies families in which the keys suggested in key value have been defined The default value of fams is currname currext The command ltxkeys executeoptions can thus be used to process keys with different prefixes and from several families E Processin
113. xkeys addbadkeynames 551 ltxkeys badkeynames list 552 ltxkeys addbadkeynames list PAGE 31 OF 66 The Itxkeys package 19th December 2011 where list is a comma separated list of inadmissible names The updating is done by merging so that entries are not repeated in the internal list of bad key names You can remove from the list of bad key names by using the following command New macro ltxkeys removebadkeynames ltxkeys removebadkeynames list a E w where again list is comma separated It is not advisable to remove any member of the default bad key names 11 Declaring options New macros ltxkeys declareoption ltxkeys unknownoptionhandler ltxkeys declareoption pref lt fam gt option dft cbk ltxkeys declareoption pref lt fam gt cbk ltxkeys unknownoptionhandler pref lt fam gt cbk The unstarred variant of ltxkeys declareoption is simply a form of ltxkeys ordkey with the difference that the key family fam is now optional and when specified must be given in angled brackets The default family name is currname currext i e the name of the class file or package and its file extension The starred x variant of ltxkeys declareoption prescribes the default action to be taken when undefined options with prefix pref and in family fam are passed to class or package You may use CurrentKey and CurrentVal within this macro to pass t
114. xkeys ifeltcountTF 1180 ltxkeys ifeltcountTF parser re1 nr list true false 1181 ltxkeys ifeltcountTF parser re1 nr listcmd true false The command ltxkeys ifeltcountTF checks if the number of elements in parser separated list list has relation rel gt lt with number nr If the test is true true is executed otherwise false is executed The starred x variant of ltxkeys ifeltcountTF will expand listcmd once before the test Double parsers and empty entries in list are ignored The default values of the optional list parser and the optional relational type rel are comma and respectively The number nr is a mandatory argument The following example returns false i e meaning x gt F Example ltxkeys ifeltcountTF 1182 ltxkeys ifeltcountTF lt 2 a b c def x T def x F 17 9 What is the numerical order of an element in a csv list New macro ltxkeys getorder 1183 ltxkeys getorder parser elt list 1184 ltxkeys getorder parser elt listcmd The command ltxkeys getorder returns in ltxkeys order the numerical order of elt in parser separated list or listcmd The value of ltxkeys order is the numerical order of the first match found The count starts from zero 0 The starred x variant will expand listcmd once before commencing the search for elt If no match is found ltxkeys orde
115. xkeys package 19th December 2011 The braces in the key values above are just to exemplify the fact that braces in key values are preserved throughout key parsing As mentioned earlier this is essential for some packages and class files 3 4 1 Style keys that share the same attributes The commands ltxkeys stylekey and ltxkeys newstylekey can be used to introduce style keys keys that share the same path or bases key prefix key family and macro prefix and callback cbk Just replace key in these commands with the comma separated list keys However some users might prefer to see these commands in their plural forms when defining several keys with the same callback Hence we also provide the following aliases New macros ltxkeys stylekeys ltxkeys newstylekeys ltxkeys stylekeys pref fam mp keys d t deps cbk ltxkeys stylekeys pref fam mp keys dft C deps cbk ltxkeys newstylekeys pref fam mp keys dft deps cbk ltxkeys newstylekeys pref fam mp keys dft deps cbk 51 52 53 54 3 5 Boolean keys New macros ltxkeys boolkey ltxkeys newboolkey ltxkeys boolkey pref fam mp key dft cbk ltxkeys boolkey pref fam mp key dft cbk HE fn ltxkeys newboolkey pref fam mp key dft cbk ltxkeys newboolkey pref fam mp key dft cbk
116. xrule 327 color mp framecolor 328 noindent 329 tboxth 330 removelastskip 331 parbox mp boxwidth PAGE 19 OF 66 The Itxkeys package 19th December 2011 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 363 364 365 366 367 368 369 370 371 372 begin mp textalign textcolor mp textcolor 2 end mp textalign Ya yh endgroup F newcommand 1txminipage 2 4 ltxkeys setkeys KV 1txminipage 1 begingroup fboxsep mp framesep fboxrule ifmp framebox mp framerule else z fi cptdimdef mp boxwidth mp width 2 fboxsep 2 fboxrule noindent begin 1lrbox tempboxa begin minipage c height s mp boxwidth killglue begin mp textalign textcolor mpO textcolor 2 end mp textalign end minipage end 1rbox killglue color mp framecolor ifmpO framebox fbox fi usebox tempboxa ifmp framebox fi endgroup begin document ltxframebox framecolor blue textcolor purple textalign left 10 Test textNendgraf endgraf test text F medskip ltxminipage framecolor blue textcolor purple framebox true textalign right 10 Test textNendgraf endgraf test text end document 4 Setting keys In the 1txkeys package there are many functions for setting keys Keys can be set by the following utilities 4 1 Setting defined keys ltxkey
117. yparser etc 93 94 If the parser is semicolon then we would have Syntaxes of nominations for choice keys 97 choice1 code callback1 choice2 code callback2 etc 98 Or 99 choice1 callback1 choice2 callback2 etc This means that if you have code or in any of the callbacks it has to be enclosed in curly braces Please recall that the default value of keyparser is semicolon keyparser is a package option This syntax also implies that if you have the keyparser in defn it has to be wrapped in curly braces Note 3 2 The keyparser in these syntaxes of nominations for choice keys could also be comma without the need to declare the package option keyparser as comma Here is the rule for parsing the alt list First the package checks if the declared key parser i e keyparser is in the alt list If the parser exists in alt then the list is parsed using this parser Otherwise the list is parsed using comma as the parser Moreover the package checks PAGE 11 OF 66 The Itxkeys package 133 if code separates choice from the callback cbk If no code is found then is assumed to be the separator But note that when there is no cbk for a nomination then neither code nor is necessary It is possible to refer to the current value of key as 1 in alt The starred x
118. ys emptifysavevaluekeys pref fam ltxkeys emptifysavevaluekeys pref fam The command ltxkeys savevaluekeys will create for the given key family and prefix a list of keys whose values should be saved at key setting time if those keys don t already exist in the list The command ltxkeys addsavevaluekeys will add to the list those keys that don t already exist in the list ltxkeys removesavevaluekeys remove those save keys that it can find in the list while the command ltxkeys undefsavevaluekeys will undefine the entire list of save keys of the given key family and prefix The command ltxkeys emptifysavevaluekeys will simplify emptify the content of the save key list The variant of the commands Macros 424 ltxkeys undefsavevaluekeys 425 ltxkeys emptifysavevaluekeys will undefine or emptify the existing save key list globally PAGE 23 OF 66 The Itxkeys package 19th December 2011 Examples ltxkeys savevaluekeys ltxkeys definekeys KV fam mp0 ord keya 2cm def x 1 1xx 1 cmd keyb John bool keyc true ifmp keyc def y 1 1lyy 1 fi choice keyd left right center ifcase order def shoot 0 or def shoot 1 or def shoot 2 fi ltxkeys savevaluekeys KV fam keya keyb keyc ltxkeys addsavevaluekeys KV fam keyd ltxkeys removesavevaluekeys KV fam keya keyb ltxkeys undefsavevaluekeys KV fam 433 434 435 436
119. ytype keyname dft cbk another set of key attributes etc 192 193 194 195 196 ltxkeys declarekeys pref fam mp keytype keyname dft cbk another set of key attributes etc 197 198 199 200 b 201 Here the default value dft and the callback cbk can be absent in all cases keytype may be any one of ford cmd sty sty bool choice The star x in sty has the same meaning as in ltxkeys stylekey above namely undefined dependants will be defined on the fly when the parent key is set The optional quantity mp is the macro prefix as in e g subsection 3 3 Choice keys must have their names associated with their admissible a1t values in the format keyname alt see example below The starred x variant of ltxkeys declarekeys can be used to define new keys in the sense of newcommand Note 3 5 Keys defined by ltxkeys declarekeys are automatically set instantly with their default values to provide default functions for immediate use Boolean keys are always initialized in this sense with false so that they aren t turned true prematurely Examples ltxkeys declarekeys 202 ltxkeys declarekeys KV fam mp0 203 Ordinary key with callback 204 ord keya 1 paperwidth leftmargin 1 relax 205 Command key with callback code is allowed before callback 206 cmd keyb 10mm code rightmargin 1 def x 1 1 1

The ltxkeys Package

Contents

Download Pdf Manuals

Related Search

Related Contents