Kolmafia - User contributions [en]

KoLmafia Properties

2016-07-17T17:42:46Z

QVamp: added missing airports

{{TOCright}}
Inside your KoLmafia "settings" directory, you should find several files. KoLmafia properties are stored in the files that end with "_prefs.txt". One of these files will start with "GLOBAL"; the settings inside are shared by all characters using the program (and some of these properties are needed by KoLmafia even when no character is logged in). The other files ending with "_prefs.txt" will start with the name of a character, one for each who has been logged in to date. (Note: the names will all be converted to lowercase.)

==Global Variables==
{| class="wikitable" border="1"
|-
! Variable Name
! scope="col" width="300" | Default Value
! Notes
|-
| addChatCommandLine
| false
|
|-
| addCreationQueue
| true
|
|-
| addStatusBarToFrames
| false
|
|-
| allowCloseableDesktopTabs
| false
|
|-
| allowNegativeTally
| true
|
|-
| allowNonMoodBurning
| true
|
|-
| alwaysGetBreakfast
| false
|
|-
| autoLogin
|
|
|-
| allowSocketTimeout
| true
|
|-
| autoHighlightOnFocus
| true
|
|-
| autoPlantHardcore
| false
|
|-
| autoPlantSoftcore
| false
|
|-
| autoSatisfyWithCloset
| false
|
|-
| autoSatisfyWithCoinmasters
| false
|
|-
| autoSatisfyWithMall
| false
|
|-
| autoSatisfyWithNPCs
| false
|
|-
| autoSatisfyWithStash
| false
|
|-
| autoSatisfyWithStorage
| true
|
|-
| breakfastHardcore
| Advanced Saucecrafting,Pastamastery,Advanced Cocktailcrafting
|
|-
| breakfastSoftcore
| Advanced Saucecrafting,Pastamastery,Advanced Cocktailcrafting
|
|-
| browserBookmarks
|
|
|-
| cacheMallSearches
| false
|
|-
| charsheetDropdown
| 1
|
|-
| chatBeep
| false
| Beep on private message in chat
|-
| chatFontSize
|
|
|-
| chatLinksUseRelay
| false
|
|-
| chatStyle
| 0
|
|-
| checkJackassHardcore
| true
|
|-
| checkJackassSoftcore
| true
|
|-
| cloverProtectActive
| true
|
|-
| coinMasterIndex
| 1
|
|-
| combatHotkey0
|
|
|-
| combatHotkey1
|
|
|-
| combatHotkey2
|
|
|-
| combatHotkey3
|
|
|-
| combatHotkey4
|
|
|-
| combatHotkey5
|
|
|-
| combatHotkey6
|
|
|-
| combatHotkey7
|
|
|-
| combatHotkey8
|
|
|-
| combatHotkey9
|
|
|-
| commandLineNamespace
|
|
|-
| connectViaAddress
| false
|
|-
| cookies.inventory
|
|
|-
| copyAsHTML
| false
|
|-
| customizedTabs
| false
|
|-
| dailyDeedsOptions
| Breakfast,Daily Dungeon,Submit Spading Data,Chips,Library Card,Telescope,Ball Pit,Styx Pixie,VIP Pool,Swimming Pool,April Shower,Bag o' Tricks,Legendary Beat,Outrageous Sombrero,Feast,Friars,Skate Park,Concert,Demon Summoning,Rage Gland,Free Rests,Hot Tub,Nuns,Oscus' Soda,Express Card,Flush Mojo,Pudding,Hatter,Melange,Ultra Mega Sour Ball,Stills,Photocopy,Putty,Camera,Banished Monsters,Romantic Arrow,Avatar of Jarlberg Staves,Bonus Adventures,Familiar Drops,Free Fights,Free Runaways,Defective Token
|
|-
| dailyDeedsVersion
| 8
|
|-
| debugBuy
| false
|
|-
| debugConsequences
| false
|
|-
| debugFoxtrotRemoval
| false
|
|-
| debugPathnames
| true
|
|-
| defaultBorderColor
| blue
|
|-
| defaultDropdown1
| 0
|
|-
| defaultDropdown2
| 1
|
|-
| defaultDropdownSplit
| 0
|
|-
| defaultLimit
| 5
|
|-
| defaultLoginServer
| 1
|
|-
| displayName
|
|
|-
| externalEditor
|
|
|-
| fixedThreadPoolSize
| 0
|
|-
| gapProtection
| false
|
|-
| getBreakfast
|
|
|-
| grabCloversHardcore
| false
|
|-
| grabCloversSoftcore
| true
|
|-
| greenScreenProtection
| false
|
|-
| grimoireSkillsHardcore
| none
|
|-
| grimoireSkillsSoftcore
| Summon Hilarious Objects
|
|-
| guiUsesOneWindow
| false
|
|-
| harvestGardenHardcore
| none
| The crop that breakfast will harvest, if in your garden.
|-
| harvestGardenSoftcore
| none
| The crop that breakfast will harvest, if in your garden.
|-
| hideServerDebugText
| false
|
|-
| highlightList
|
|
|-
| http.proxyHost
|
|
|-
| http.proxyPassword
|
|
|-
| http.proxyPort
|
|
|-
| http.proxyUser
|
|
|-
| https.proxyHost
|
|
|-
| https.proxyPassword
|
|
|-
| https.proxyPort
|
|
|-
| https.proxyUser
|
|
|-
| initialDesktop
| AdventureFrame,CommandDisplayFrame, MallSearchFrame,GearChangeFrame,SkillBuffFrame
| starting tab configuration
|-
| initialFrames
| RecentEventsFrame
|
|-
| innerChatColor
| #ffa98c
|
|-
| innerTabColor
| #8ca9ff
|
|-
| itemManagerIndex
| 0
|
|-
| lastBuffRequestType
| 0
|
|-
| lastRelayUpdate
|
|
|-
| lastRssUpdate
| 0
|
|-
| lastRssVersion
|
|
|-
| lastUserAgent
|
|
|-
| lastUsername
|
|
|-
| libramSkillsHardcore
| none
|
|-
| libramSkillsSoftcore
| none
|
|-
| logAcquiredItems
| true
|
|-
| logBattleAction
| true
|
|-
| logBrowserInteractions
| false
|
|-
| logChatMessages
| true
|
|-
| logChatRequests
| false
|
|-
| logCleanedHTML
| false
|
|-
| logDecoratedResponses
| false
|
|-
| logFamiliarActions
| true
|
|-
| logGainMessages
| true
|
|-
| logReadableHTML
| false
|
|-
| loginRecoveryHardcore
| false
|
|-
| loginRecoverySoftcore
| true
|
|-
| loginScript
|
|
|-
| loginServerName
|
|
|-
| loginWindowLogo
| lantern.jpg
|
|-
| logMonsterHealth
| false
|
|-
| logoutScript
|
|
|-
| logReverseOrder
| false
|
|-
| logStatGains
| true
|
|-
| logStatusEffects
| true
|
|-
| logStatusOnLogin
| false
|
|-
| macroDebug
| false
|
|-
| macroLens
| false
|
|-
| mementoListActive
| false
|
|-
| mergeHobopolisChat
| false
|
|-
| outerChatColor
| #b4460f
|
|-
| outerTabColor
| #0f46b4
|
|-
| pathedSummonsHardcore
| true
|
|-
| pathedSummonsSoftcore
| false
|
|-
| preferredWebBrowser
|
|
|-
| previousNotifyList
| <>
|
|-
| previousUpdateVersion
|
|
|-
| previousUpdateRevision
| 0
|
|-
| protectAgainstOverdrink
| true
|
|-
| proxySet
| false
|
|-
| readManualHardcore
| true
|
|-
| readManualSoftcore
| true
|
|-
| relayAddsCustomCombat
| true
|
|-
| relayAddsDiscoHelper
| false
|
|-
| relayAddsGraphicalCLI
| false
|
|-
| relayAddsQuickScripts
| false
|
|-
| relayAddsRestoreLinks
| true
|
|-
| relayAddsUpArrowLinks
| true
|
|-
| relayAddsUseLinks
| true
|
|-
| relayAddsWikiLinks
| false
|
|-
| relayAllowRemoteAccess
| false
|
|-
| relayBrowserOnly
| false
|
|-
| relayFormatsChatText
| true
|
|-
| relayHidesJunkMallItems
| false
|
|-
| relayMaintainsEffects
| false
|
|-
| relayMaintainsHealth
| false
|
|-
| relayMaintainsMana
| false
|
|-
| relayOverridesImages
| false
|
|-
| relayRunsAfterAdventureScript
| false
|
|-
| relayRunsBeforeBattleScript
| false
|
|-
| relayRunsBeforePVPScript
| false
|
|-
| relayScriptButtonFirst
| false
|
|-
| relaySkillButtonCount
| 5
|
|-
| relayTextualizesEffects
| false
|
|-
| relayTrimsZapList
| false
|
|-
| relayUsesInlineLinks
| true
|
|-
| relayUsesIntegratedChat
| false
|
|-
| relayViewsCustomItems
| false
|
|-
| relayWarnOnRecoverFailure
| true
|
|-
| removeMalignantEffects
| false
|
|-
| saveSettingsOnSet
| true
|
|-
| saveState
|
|
|-
| saveStateActive
|
|
|-
| scriptButtonPosition
| 0
|
|-
| scriptList
| restore hp | restore mp
|
|-
| sharePriceData
| false
|
|-
| showAllRequests
| false
|
|-
| showAnnouncements
| true
| Display special KoL announcements from the login page
|-
| showExceptionalRequests
| false
|
|-
| simpleSvnUpdate
| true
|
|-
| statusDropdown
| 0
|
|-
| stealthLogin
| true
|
|-
| svnInstallDependencies
| true
|
|-
| svnShowCommitMessages
| false
|
|-
| svnUpdateOnLogin
| false
|
|-
| swingLookAndFeel
|
|
|-
| switchEquipmentForBuffs
| false
|
|-
| syncAfterSvnUpdate
| false
|
|-
| tomeSkillsHardcore
| Summon Snowcone
|
|-
| tomeSkillsSoftcore
| all
|
|-
| toolbarPosition
| 1
|
|-
| useChatToolbar
| true
|
|-
| useContactsFrame
| true
|
|-
| useCrimboToysHardcore
| false
|
|-
| useCrimboToysSoftcore
| true
|
|-
| useDecoratedTabs
|
|
|-
| useDevProxyServer
| false
|
|-
| useDockIconBadge
| false
|
|-
| useImageCache
| true
|
|-
| useLastUserAgent
| false
|
|-
| useNaiveSecureLogin
| false
|
|-
| useSecureLogin
| false
|
|-
| useShinyTabbedChat
| true
|
|-
| useSystemTrayIcon
| false
|
|-
| useTabbedChatFrame
| true
|
|-
| useToolbars
| true
|
|-
| useZoneComboBox
| false
|
|-
| userAgent
|
|
|-
| verboseSpeakeasy
| false
|
|-
| visitLoungeHardcore
| true
|
|-
| visitLoungeSoftcore
| true
|
|-
| visitRumpusHardcore
| true
|
|-
| visitRumpusSoftcore
| true
|
|}

==Per-Account Variables==
Several categories of Per-Account preferences ([[Daily Variables]], [[Choice Adventures]], and [[Quest Tracking Preferences]]) have their own pages and are not listed here.

===Daily Variables===
See page [[Daily Variables]].

===Choice Adventures===
See page [[Choice Adventures]].

===Quest Tracking===
See page [[Quest Tracking Preferences]].

===User-defined variables===
In addition to setting the variables that KoLmafia predefines, you can also create any others to cover any information you wish. As you do so, keep in mind that while you can clear a variable’s value to the null string, there is currently no way to delete a key (aside from editing the .txt file in the text processor of your choice and deleting the line that contains the key).

{| class="wikitable" border="1"
|-
! Variable Name
! scope="col" width="300" | Default Value
! Notes
|-
| addingScrolls
| -1
|
|-
| afterAdventureScript
|
|
|-
| arcadeGameHints
| false
|
|-
| autoAbortThreshold
| -0.05
| Abort adventuring at this percentage of HP. (-0.05 means if HP restoration failed)
|-
| autoAntidote
| 0
| Use antidotes in combat
|-
| autoBuyPriceLimit
| 20000
| Don't auto purchase anything that costs more than this
|-
| autoCraft
| true
| Automatically spend 10 meat to create a badass belt or Bonerdagon necklace if the components are available
|-
| autoQuest
| true
|
|-
| autoEntangle
| false
| Use Entangling Noodles at the beginning of combat
|-
| autoGarish
| false
| If true, when attempting to eat lasagna, will attempt to automatically acquire and use a {{kolwiki|potion of the field gar}}
|-
| autoManaRestore
| true
| Restore MP in combat
|-
| autoOlfact
|
| Automatically cast Olfaction
|-
| autoPotionID
| false
| Attempt to ID ! potions in combat
|-
| autoPutty
|
| Automatically use Spooky Putty
|-
| autoRepairBoxServants
| true
| Create in-a-boxen before cooking or mixing
|-
| autoSphereID
| false
| Attempt to ID spheres from the Hidden City
|-
| autoSteal
| true
| Attempt to pickpocket in combat
|-
| autostartGalaktikQuest
| true
| Get Doc Galaktik's Quest at the start of ascension
|-
| autoTuxedo
| false
| If true, when drinking a martini, automatically attempts to equip a {{kolwiki|tuxedo shirt}} first
|-
| availableCandyCredits
| 0
|
|-
| availableDimes
| 0
|
|-
| availableQuarters
| 0
|
|-
| availableStoreCredits
| 0
|
|-
| availableSwagger
| 0
|
|-
| ballpitBonus
| 1
|
|-
| banishedMonsters
|
|
|-
| banishingShoutMonsters
|
|
|-
| bankedKarma
| 0
|
|-
| barrelGoal
| 1
|
|-
| bartenderTurnsUsed
| 0
|
|-
| basementMallPrices
| 1
|
|-
| battleAction
| attack with weapon
|
|-
| beeCounter
| 0
|
|-
| beforePVPScript
|
|
|-
| betweenBattleScript
|
|
|-
| bigBrotherRescued
| false
|
|-
| birdformCold
| 0
|
|-
| birdformHot
| 0
|
|-
| birdformRoc
| 0
|
|-
| birdformSleaze
| 0
|
|-
| birdformSpooky
| 0
|
|-
| birdformStench
| 0
|
|-
| blackBartsBootyAvailable
| true
|
|-
| blackPuddingsDefeated
| 0
|
|-
| blackForestProgress
| 0
|
|-
| blankOutUsed
| 0
| Tracks current amount of active Blank-out
|-
| boneAbacusVictories
| 0
|
|-
| booPeakProgress
| 100
|
|-
| borisPoints
| 0
|
|-
| breakableHandling
| 1
|
|-
| breakableHandling1964
| 2
|
|-
| brodenBacteria
| 0
|
|-
| brodenSprinkles
| 0
|
|-
| buffBotCasting
|
|
|-
| buffBotMessageDisposal
| 0
|
|-
| buffBotPhilanthropyType
| 1
|
|-
| buffJimmyIngredients
| 0
|
|-
| burnoutsDefeated
| 0
|
|-
| buyScript
|
|
|-
| cameraMonster
|
|
|-
| camerasUsed
| 0
|
|-
| carboLoading
| 0
|
|-
| cellarLayout
| 0
|
|-
| charitableDonations
| 0
|
|-
| chasmBridgeProgress
| 0
|
|-
| chatbotScript
|
|
|-
| chatbotScriptExecuted
| false
|
|-
| chatLiterate
| false
|
|-
| chatServesUpdates
| false
|
|-
| chefTurnsUsed
| 0
|
|-
| chessboardsCleared
| 0
| Number of queen cookies acquired from chessboards (max 50)
|-
| chosenTrip
|
|
|-
| cinderellaMinutesToMidnight
| 0
| Time left while doing the stepmother section of the {{kolwiki|grimstone mask}} content
|-
| cinderellaScore
| 0
| Current score while doing the stepmother section of the {{kolwiki|grimstone mask}} content
|-
| grimstoneMaskPath
|
|
|-
| clanAttacksEnabled
| false
|
|-
| coldAirportAlways
| false
| Set to true if you use an {{kolwiki|airplane charter: The Glaciest}}
|-
| considerShadowNoodles
| false
|
|-
| counterScript
|
|
|-
| corralUnlocked
| false
|
|-
| crappyCameraMonster
|
|
|-
| crimboTreeDays
| 7
|
|-
| crudeMonster
|
|
|-
| currentEasyBountyItem
|
|
|-
| currentExtremity
| 0
|
|-
| currentHardBountyItem
|
|
|-
| currentHippyStore
| none
|
|-
| currentJunkyardTool
|
|
|-
| currentJunkyardLocation
|
|
|-
| currentMood
| default
|
|-
| currentNunneryMeat
| 0
|
|-
| currentSpecialBountyItem
|
|
|-
| customCombatScript
| default
|
|-
| cyrptAlcoveEvilness
| 0
|
|-
| cyrptCrannyEvilness
| 0
|
|-
| cyrptNicheEvilness
| 0
|
|-
| cyrptNookEvilness
| 0
|
|-
| cyrptTotalEvilness
| 0
|
|-
| dampOldBootPurchased
| false
|
|-
| dbNemesisSkill1
| 0
|
|-
| dbNemesisSkill2
| 0
|
|-
| dbNemesisSkill3
| 0
|
|-
| defaultFlowerLossMessage
|
|
|-
| defaultFlowerWinMessage
|
|
|-
| demonName1
|
| Name of demon that gives pies
|-
| demonName2
|
| Name of demon that gives Preternatural Greed
|-
| demonName3
|
| Name of demon that gives Fit To Be Tide
|-
| demonName4
|
| Name of demon that gives Big Flaming Whip
|-
| demonName5
|
| Name of demon that gives Demonic Taint
|-
| demonName6
| Tatter
| Name of demon that gives pile of smoking rags
|-
| demonName7
| Ak'gyxoth
| Name of demon that gives drinks
|-
| demonName8
|
| Name of demon found in the Nemesis' Lair
|-
| demonName9
|
| Name of demon that gives Burning, Man
|-
| desertExploration
| 0
|
|-
| desktopHeight
| 600
|
|-
| desktopWidth
| 800
|
|-
| dnaSyringe
|
|
|-
| dolphinItem
|
|
|-
| envyfishMonster
|
|
|-
| flyeredML
| 0
|
|-
| fossilB
| 0
| Number of bat teeth on the fossilized necklace
|-
| fossilD
| 0
| Number of demon teeth on the fossilized necklace
|-
| fossilN
| 0
| Number of baboon teeth on the fossilized necklace
|-
| fossilP
| 0
| Number of spider teeth on the fossilized necklace
|-
| fossilS
| 0
| Number of serpent teeth on the fossilized necklace
|-
| fossilW
| 0
| Number of wyrm teeth on the fossilized necklace
|-
| fratboysDefeated
| 0
|
|-
| gameProBossSpecialPower
| Unknown
|
|-
| ghostPencil1
| false
|
|-
| ghostPencil2
| false
|
|-
| ghostPencil3
| false
|
|-
| ghostPencil4
| false
|
|-
| ghostPencil5
| false
|
|-
| ghostPencil6
| false
|
|-
| ghostPencil7
| false
|
|-
| ghostPencil8
| false
|
|-
| ghostPencil9
| false
|
|-
| goldenMrAccessories
| 0
|
|-
| gongPath
| 0
|
|-
| gourdItemCount
| 5
|
|-
| grimstoneCharge
| 0
| Track combat turns with Grimstone Golem
|-
| guardTurtlesFreed
| 0
| Number of times that [http://kol.coldfront.net/thekolwiki/index.php/Cold-Blooded_Warm_Fuzzies guard turtles have been freed] this ascension.
|-
| guyMadeOfBeesCount
| 0
|
|-
| guyMadeOfBeesDefeated
| false
|
|-
| hardcorePVPWarning
| false
| If true, will warn you if you click on the Prism with a broken Hippy Stone and PVP fights remaining
|-
| heavyRainsStartingThunder
| 0
|
|-
| heavyRainsStartingRain
| 0
|
|-
| heavyRainsStartingLightning
| 0
|
|-
| heroDonationBoris
| 0
| Meat donated to Boris
|-
| heroDonationJarlsberg
| 0
| Meat donated to Jarlsberg
|-
| heroDonationSneakyPete
| 0
| Meat donated to Sneaky Pete
|-
| hippiesDefeated
| 0
|
|-
| hotAirportAlways
| false
| Set to true if you use an {{kolwiki|airplane charter: That 70s Volcano}}
|-
| hpAutoRecovery
| -0.05
|
|-
| hpAutoRecoveryItems
| cannelloni cocoon;scroll of drastic healing;tongue of the walrus;lasagna bandages;doc galaktik's ailment ointment
|
|-
| hpAutoRecoveryTarget
| 1.0
|
|-
| iceSculptureMonster
|
|
|-
| invalidBuffMessage
| You sent an amount which does not correspond to a valid buff amount.
|
|-
| jarlsbergPoints
| 0
| Number of bonus skill points earned by doing {{kolwiki|Avatar of Jarlsberg}} ascensions
|-
| jungCharge
| 0
|
|-
| kingLiberated
| false
|
|-
| kingLiberatedScript
|
|
|-
| knownAscensions
| -1
|
|-
| kolhsTotalSchoolSpirited
| 0
|
|-
| lassoTraining
|
| Records your current {{kolwiki|sea lasso}} adjective.
|-
| lastAdventure
|
|
|-
| lastAnticheeseDay
| -5
|
|-
| lastArcadeAscension
| -1
|
|-
| lastBadMoonReset
| -1
|
|-
| lastBangPotion819
|
|
|-
| lastBangPotion820
|
|
|-
| lastBangPotion821
|
|
|-
| lastBangPotion822
|
|
|-
| lastBangPotion823
|
|
|-
| lastBangPotion824
|
|
|-
| lastBangPotion825
|
|
|-
| lastBangPotion826
|
|
|-
| lastBangPotion827
|
|
|-
| lastBangPotionReset
| -1
|
|-
| lastBattlefieldReset
| -1
|
|-
| lastBreakfast
| -1
|
|-
| lastCastleGroundUnlock
| -1
|
|-
| lastCastleTopUnlock
| -1
|
|-
| lastCellarReset
| -1
|
|-
| lastChanceBurn
|
| CLI command executed at lastChanceThreshold ("#" is replaced by the amount of MP to burn)
|-
| lastChanceThreshold
| 100
| amount of unburned MP at which alternatives to extending existing buffs will be considered
|-
| lastChessboard
|
|
|-
| lastChasmReset
| -1
|
|-
| lastCouncilVisit
| 0
|
|-
| lastCounterDay
| -1
|
|-
| lastDesertUnlock
| -1
|
|-
| lastDispensaryOpen
| -1
|
|-
| lastDoorCodeReset
| -1
|
|-
| lastDwarfDiceRolls
|
|
|-
| lastDwarfDigitRunes
| -------
|
|-
| lastDwarfEquipmentRunes
|
|
|-
| lastDwarfFactoryItem118
|
|
|-
| lastDwarfFactoryItem119
|
|
|-
| lastDwarfFactoryItem120
|
|
|-
| lastDwarfFactoryItem360
|
|
|-
| lastDwarfFactoryItem361
|
|
|-
| lastDwarfFactoryItem362
|
|
|-
| lastDwarfFactoryItem363
|
|
|-
| lastDwarfFactoryItem364
|
|
|-
| lastDwarfFactoryItem365
|
|
|-
| lastDwarfFactoryItem910
|
|
|-
| lastDwarfFactoryItem3199
|
|
|-
| lastDwarfOfficeItem3208
|
|
|-
| lastDwarfOfficeItem3209
|
|
|-
| lastDwarfOfficeItem3210
|
|
|-
| lastDwarfOfficeItem3211
|
|
|-
| lastDwarfOfficeItem3212
|
|
|-
| lastDwarfOfficeItem3213
|
|
|-
| lastDwarfOfficeItem3214
|
|
|-
| lastDwarfOreRunes
|
|
|-
| lastDwarfFactoryReset
| -1
|
|-
| lastDwarfHopper1
|
|
|-
| lastDwarfHopper2
|
|
|-
| lastDwarfHopper3
|
|
|-
| lastDwarfHopper4
|
|
|-
| lastEVHelmetValue
| 0
|
|-
| lastEVHelmetReset
| -1
|
|-
| lastEasterEggBalloon
| -1
|
|-
| lastEmptiedStorage
| -1
| Number of the last ascension that Hangk's storage was emptied.
|-
| lastEncounter
|
|
|-
| lastFilthClearance
| -1
|
|-
| lastGoofballBuy
| -1
|
|-
| lastGuildStoreOpen
| -1
|
|-
| lastGuyMadeOfBeesReset
| -1
|
|-
| lastHiddenCityAscension
| 0
|
|-
| lastHippyCall
| -1
|
|-
| lastKingLiberation
| -1
|
|-
| lastLightsOutTurn
| -1
|
|-
| lastMushroomPlot
| -1
|
|-
| lastMessageId
|
|
|-
| lastMiningReset
| -1
|
|-
| lastPaperStripReset
| -1
|
|-
| lastPaperStrip3144
|
|
|-
| lastPaperStrip4138
|
|
|-
| lastPaperStrip4139
|
|
|-
| lastPaperStrip4140
|
|
|-
| lastPaperStrip4141
|
|
|-
| lastPaperStrip4142
|
|
|-
| lastPaperStrip4143
|
|
|-
| lastPaperStrip4144
|
|
|-
| lastPirateEphemera
|
|
|-
| lastPirateEphemeraReset
| -1
|
|-
| lastPirateInsult1
| false
|
|-
| lastPirateInsult2
| false
|
|-
| lastPirateInsult3
| false
|
|-
| lastPirateInsult4
| false
|
|-
| lastPirateInsult5
| false
|
|-
| lastPirateInsult6
| false
|
|-
| lastPirateInsult7
| false
|
|-
| lastPirateInsult8
| false
|
|-
| lastPirateInsultReset
| -1
|
|-
| lastPlusSignUnlock
| -1
|
|-
| lastPorkoBoard
|
|
|-
| lastPorkoPayouts
|
|
|-
| lastPorkoExpected
|
|
|-
| lastQuartetAscension
| -1
|
|-
| lastQuartetRequest
| 0
|
|-
| lastSecondFloorUnlock
| -1
|
|-
| lastSemirareReset
| -1
|
|-
| lastTavernAscension
| 0
|
|-
| lastTavernSquare
| 0
|
|-
| lastTelescopeReset
| -1
|
|-
| lastTowerClimb
| -1
|
|-
| lastVioletFogMap
| 0
|
|-
| lastWartDinseyDefeated
| -1
| Tracks defeat of {{kolwiki|Wart Dinsey}}
|-
| lastZapperWand
| 0
|
|-
| lightsOutAutomation
| 1
| Highlights/automatically selects correct option during {{kolwiki|Lights Out Quest}} noncombats
|-
| louvreDesiredGoal
| 7
|
|-
| louvreGoal
| 0
|
|-
| louvreOverride
|
|
|-
| makeFriendsMonster
|
|
|-
| manaBurnSummonThreshold
| 10
|
|-
| manaBurningThreshold
| -0.05
|
|-
| maximizerMRUSize
| 5
|
|-
| maximizerCombinationLimit
| 0
|
|-
| maxManaBurn
| 1000
|
|-
| mayflyExperience
| 0
| Uses of mayfly bait necklace. Reset each ascension.
|-
| meansuckerPrice
| 400
|
|-
| meatDropSpading
| false
|
|-
| mineLayout1
|
|
|-
| mineLayout2
|
|
|-
| mineLayout3
|
| Stores the results of each twinkly rock mined in {{kolwiki|Anemone Mine (Mining)}}. This is used by the relay browser to display the results in-game.
|-
| mineLayout4
|
|
|-
| miniAdvClass
| 0
|
|-
| mmgAutoConfirmBets
| false
|
|-
| mmgDisabled
| false
|
|-
| mmgSearchMinimum
|
|
|-
| mmgSearchMaximum
|
|
|-
| moleTunnelLevel
| 0
|
|-
| mpAutoRecovery
| 0.0
|
|-
| mpAutoRecoveryItems
| phonics down;knob goblin superseltzer;mountain stream soda;magical mystery juice;knob goblin seltzer;cherry cloaca cola;soda water
|
|-
| mpAutoRecoveryTarget
| 0.3
|
|-
| munchiesPillsUsed
| 0
|
|-
| nextAdventure
|
|
|-
| nextSpookyravenElizabethRoom
| The Haunted Storage Room
|
|-
| nextSpookyravenStephenRoom
| The Haunted Bedroom
|
|-
| nosyNoseMonster
|
|
|-
| oceanAction
| savecontinue
|
|-
| oceanDestination
| manual
|
|-
| olfactedMonster
| unknown
|
|-
| parasolUsed
| 0
|
|-
| pastaThrall1
|
|
|-
| pastaThrall2
|
|
|-
| pastaThrall3
|
|
|-
| pastaThrall4
|
|
|-
| pastaThrall5
|
|
|-
| pastaThrall6
|
|
|-
| pastaThrall7
|
|
|-
| pastaThrall8
|
|
|-
| pendingMapReflections
| 0
|
|-
| peteMotorbikeTires
|
|
|-
| peteMotorbikeGasTank
|
|
|-
| peteMotorbikeHeadlight
|
|
|-
| peteMotorbikeCowling
|
|
|-
| peteMotorbikeMuffler
|
|
|-
| peteMotorbikeSeat
|
|
|-
| photocopyMonster
|
|
|-
| pieStuffing
|
|
|-
| pirateSwagger
| 0
|
|-
| plantingDate
|
|
|-
| plantingDay
| -1
|
|-
| plantingLength
|
|
|-
| plantingScript
|
|
|-
| poolSharkCount
| 0
| Number of times "Rack 'em up" was selected at {{kolwiki|A Shark's Chum}}
|-
| postAscensionScript
|
|
|-
| preAscensionScript
|
|
|-
| preBlackbirdFamiliar
|
|
|-
| promptAboutCrafting
| 1
| Prompt when crafting would spend an adventure. (0=never, 1=one-time confirmation, 2=always)
|-
| pyramidPosition
| 1
|
|-
| pyramidBombUsed
| false
|
|-
| rainDohMonster
|
|
|-
| raveCombo1
|
| Rave Concentration
|-
| raveCombo2
|
| Rave Nirvana
|-
| raveCombo3
|
| Rave Knockout
|-
| raveCombo4
|
| Rave Bleeding
|-
| raveCombo5
|
| Rave Steal
|-
| raveCombo6
|
| Rave Substats
|-
| reanimatorArms
| 0
|
|-
| reanimatorLegs
| 0
|
|-
| reanimatorSkulls
| 0
|
|-
| reanimatorWeirdParts
| 0
|
|-
| reanimatorWings
| 0
|
|-
| recentLocations
| 5
|
|-
| recoveryScript
|
|
|-
| relayCounters
|
|
|-
| relayShowSpoilers
| false
|
|-
| relayShowWarnings
| true
|
|-
| relocatePygmyJanitor
| -1
|
|-
| relocatePygmyLawyer
| -1
|
|-
| rememberDesktopSize
| false
|
|-
| requireBoxServants
| false
|
|-
| requireSewerTestItems
| false
|
|-
| retrieveContacts
| true
|
|-
| rumpelstiltskinTurnsUsed
| 0
|
|-
| rumpelstiltskinKidsRescued
| 0
|
|-
| safePickpocket
| true
|
|-
| scriptMRULength
| 0
|
|-
| scriptMRUList
|
|
|-
| seahorseName
|
|
|-
| semirareCounter
| 0
|
|-
| semirareLocation
|
|
|-
| serverAddsCustomCombat
| false
|
|-
| sexChanges
| 0
|
|-
| showGainsPerUnit
| false
|
|-
| showNoSummonOnly
| false
|
|-
| showTurnFreeOnly
| false
|
|-
| sideDefeated
| neither
|
|-
| sidequestArenaCompleted
| none
|
|-
| sidequestFarmCompleted
| none
|
|-
| sidequestJunkyardCompleted
| none
|
|-
| sidequestLighthouseCompleted
| none
|
|-
| sidequestNunsCompleted
| none
|
|-
| sidequestOrchardCompleted
| none
|
|-
| singleFamiliarRun
| 0
|
|-
| skateParkStatus
| war
|
|-
| skillLevel46
| 2
|
|-
| skillLevel47
| 1
|
|-
| skillLevel48
| 2
|
|-
| sleazeAirportAlways
| false
| Set to true if you use an {{kolwiki|airplane charter: Spring Break Beach}}
|-
| slimelingFullness
| 0.0
|
|-
| slimelingStacksDropped
| 0
|
|-
| slimelingStacksDue
| 0
|
|-
| sneakyPetePoints
| 0
| Number of bonus skill points earned by doing {{kolwiki|Avatar of Sneaky Pete}} ascensions
|-
| sortByRoom
| true
|
|-
| spadingData
|
|
|-
| spookyAirportAlways
| false
| Set to true if you use an {{kolwiki|airplane charter: Conspiracy Island}}
|-
| spookyPuttyMonster
|
|
|-
| stationaryButton1
|
|
|-
| stationaryButton2
|
|
|-
| stationaryButton3
|
|
|-
| stationaryButton4
|
|
|-
| stationaryButton5
|
|
|-
| stenchAirportAlways
| false
| Set to true if you use an {{kolwiki|airplane charter: Dinseylandfill}}
|-
| suppressInappropriateNags
| false
| Facilitates end-user suppression of inappropriate nags.
|-
| suppressPotentialMalware
| false
| If true, prevents the relay browser from connecting to known malware attack vectors.
|-
| tacoDanCocktailSauce
| 0
|
|-
| tacoDanFishMeat
| 0
|
|-
| [[tavernLayout]]
| 0000000000000000000000000
|
|-
| telescope1
|
|
|-
| telescope2
|
|
|-
| telescope3
|
|
|-
| telescope4
|
|
|-
| telescope5
|
|
|-
| telescope6
|
|
|-
| telescope7
|
|
|-
| telescopeLookedHigh
| false
|
|-
| telescopeUpgrades
| 0
|
|-
| testudinalTeachings
|
|
|-
| thanksMessage
| Thank you for the donation!
|
|-
| timeTowerAvailable
| false
|
|-
| trackLightsOut
| false
| Track {{kolwiki|Lights Out Quest}}. Can be set with "spookyraven" CLI command.
|-
| trapperOre
| chrome ore
|
|-
| turtleBlessingTurns
| 0
|
|-
| uneffectWithHotTub
| true
| If true, during HC/ronin KoLmafia will spend a {{kolwiki|hot tub}} use to remove a negative effect instead of a {{kolwiki|soft green echo eyedrop antidote}}. Does not change casual/aftercore behavior.
|-
| usable1HWeapons
| 3
|
|-
| usable1xAccs
| 1
|
|-
| usable2HWeapons
| 1
|
|-
| usable3HWeapons
| 1
|
|-
| usableAccessories
| 3
|
|-
| usableHats
| 2
|
|-
| usableOffhands
| 1
|
|-
| usableOther
| 1
|
|-
| usablePants
| 1
|
|-
| usableShirts
| 1
|
|-
| valueOfAdventure
| 500
|
|-
| valueOfInventory
| 1.8
|
|-
| valueOfStill
| 0
|
|-
| valueOfTome
| 0
|
|-
| verboseMaximizer
| false
|
|-
| violetFogGoal
| 0
|
|-
| violetFogLayout
|
|
|-
| warProgress
| unstarted
|
|-
| waxMonster
|
|
|-
| welcomeBackAdv
| 0
|
|-
| workteaClue
|
|
|-
| unknownRecipe3542
| true
|
|-
| unknownRecipe3543
| true
|
|-
| unknownRecipe3544
| true
|
|-
| unknownRecipe3545
| true
|
|-
| unknownRecipe3546
| true
|
|-
| unknownRecipe3547
| true
|
|-
| unknownRecipe3548
| true
|
|-
| unknownRecipe3749
| true
|
|-
| unknownRecipe3751
| true
|
|-
| unknownRecipe4172
| true
|
|-
| unknownRecipe4173
| true
|
|-
| unknownRecipe4174
| true
|
|-
| yearbookCameraAscensions
| 0
|
|-
| yearbookCameraPending
| false
|
|-
| yearbookCameraTarget
|
|
|-
| yearbookCameraUpgrades
| 0
|
|-
| zeppelinProtestors
| 0
| Counts protesters removed from {{kolwiki|A Mob of Zeppelin Protesters}}
|-
| zombiePoints
| 0
|
|}

{{SeeAlso|get_property|set_property}}

{{PropertyNav}}

[[Category:Scripting]]

Data Structures

2012-09-01T20:27:32Z

QVamp: expanded sort section with more information and a full example

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates new_pricelist */

my_pricelist = new_pricelist;
</syntaxhighlight>}}

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
</syntaxhighlight>}}

If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(copy-pasted from Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Starting with SVN revision 1311 of KoLmafia, ASH now supports a new kind of structured data: the record. Here is a little example of how you declare a record and variables of the new type you've created by doing so.

{{CodeSample|code=<syntaxhighlight>
record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;
</syntaxhighlight>}}

What I've done with the above is declare a new data type which I've named "my_type". Having declared the new type, I can use it (almost) anywhere that I can use a built-in type name. I declared a variable, "rvar", of that type, and I defined a map, "mrvar", which maps keys of type integer to values of type my_type.

The new type, "my_type" is a "composite" type. It contains four fields. "ifield" is an integer. "sfield" is a string. "rfield" is another composite field: an anonymous record containing two integers named "first" and "second". Finally, "mfield" is a map from [int, int] to int.

As you can see, a record can combine data of all the types ASH supports: primitive, aggregate, and composite.

Having defined the new data type and several variables using it, here are some examples of how to access the fields.

{{CodeSample|code=<syntaxhighlight>
rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.rfield.second = 2000;
rvar.mfield[ 2, 3 ] = 12;

mrvar[ 1 ] = rvar;

foreach key in mrvar
foreach key1, key2 in mrvar[key].mfield
print( "val = " + mrvar[key].mfield[key1,key2] );
</syntaxhighlight>}}

As you can see, if you have a variable that is a record, you access the fields of the record by following the variable name with ".<field name>". The resulting value will be of whatever type you declared in the definition of the record. If the value is a map, you can give a list of keys within [], just like any other map. If the value is another record, you can access the fields of the nested record by using another ".<field name>".

If you are familiar with Pascal "records" or C/C++ "structs", this should all be comfortably familiar.

Finally, if you create a map whose values is a record, the file_to_map and map_to_file built-in ASH functions will Do The Right Thing; they will efficiently and reliably save and restore your data.

[[Category:Scripting]]

Miscellaneous Functions

2012-02-12T04:41:15Z

QVamp: added link to get more info on maps

{{TOCright}}
== Chat Functions ==
{{Flink|void|chat_clan|string}}
{{Flink|void|chat_clan|string|string|desc=Sends a message to clan chat.}}
{{Flink|void|chat_macro|string|desc=Submits a chat macro to KoL.}}
{{Flink|void|chat_notify|string|string|desc=Sends a notification to the player's own chat.}}
{{Flink|void|chat_private|string|string|desc=Sends a private message to another player.}}
{{Flink|boolean|is_online|string|desc=Check to see if a player is online.}}
{{Flink|boolean [string]|who_clan|desc=Returns a list of whom is in your clan and if they are in chat.}}

== Debugging Functions ==
{{Flink|void|disable|string|desc=Disables the specified function.}}
{{Flink|void|enable|string|desc=Enables the specified function.}}
{{Flink|buffer|load_html|string|desc=Works like visit_url(), but for debugging.}}
{{Flink|string|make_url|string|boolean|boolean|desc=Crafts the URL to visit.}}

== Map Management Functions ==
''Note: Information about maps (including creating, assigning, and removing keys, can be found at:
[[Data Structures#Maps|Map Data Structures]]''

{{Flink|boolean|file_to_map|string|aggregate|desc=Loads a map from a tab-delimited text file.}}
{{Flink|boolean|map_to_file|aggregate|string|desc=Saves a map to a tab-delimited text file.}}
{{Flink|int|count|aggregate|desc=Returns the number of defined keys for the specified aggregate.}}
{{Flink|void|clear|aggregate|desc=Removes all keys from the specified aggregate.}}

== Time Functions ==
{{Flink|string|format_date_time|string|string|string|desc=Reformats dates.}}
{{Flink|int|gameday_to_int|desc=Returns the current KoL date as an integer.}}
{{Flink|string|gameday_to_string|desc=Returns the current KoL date as a string.}}
{{Flink|int|gametime_to_int|desc=Returns the current KoL time in ms as an integer.}}
{{Flink|string|now_to_string|string|desc=Returns current local time/date in SimpleDateFormat format.}}
{{Flink|string|time_to_string|desc=Returns the current local time in HH:mm:ss z format.}}
{{Flink|string|today_to_string|desc=Returns the current local day in ISO format.}}

== User Interaction ==
{{Flink|void|print|string|{{opt|string}}|desc=Prints to CLI and status line of Adventuring window, optionally in a specified color.}}
{{Flink|void|print_html|string|desc=Prints to CLI, parsing any included html.}}
{{Flink|void|logprint|string|desc=Prints to the session log.}}
{{Flink|void|wait|int}}
{{Flink|void|waitq|int|desc=Sleeps for the specified number of seconds.}}
{{Flink|boolean|user_confirm|string|desc=Allows user input in Y/N format.}}

== Other Functions ==
{{Flink|void|abort|{{opt|string}}|desc=Aborts the current script with an optional message.}}
{{Flink|boolean|cli_execute|string|desc=Executes the given command as if it were entered into the CLI.}}
{{Flink|string|get_property|string|desc=Gets a global or user preference as appropriate.}}
{{Flink|void|set_property|string|string|desc=Sets a global or user preference as appropriate.}}
{{Flink|void|batch_open|desc=Used to mark the beginning of a block of functions to operate in batch mode (see page for {{f|batch_close}} for details).}}
{{Flink|boolean|batch_close|desc=Used to mark the end of a block of functions to operate in batch mode (see page for details).}}
{{Flink|int|get_revision|desc=Returns the current KoLmafia revision number.}}
{{Flink|string|get_version|desc=Returns the most recent KoLmafia version.}}

Additional functions that are considered not really to be ash functions are available in [[Miscellaneous ASH Features#Special Syntax Functions|Misc ASH Features]]

[[Category:Scripting]]

Miscellaneous Functions

2011-09-16T15:38:06Z

QVamp: added link to similar section

{{TOCright}}
== Chat Functions ==
{{Flink|void|chat_clan|string}}
{{Flink|void|chat_clan|string|string|desc=Sends a message to clan chat.}}
{{Flink|void|chat_macro|string|desc=Submits a chat macro to KoL.}}
{{Flink|void|chat_notify|string|string|desc=Sends a notification to the player's own chat.}}
{{Flink|void|chat_private|string|string|desc=Sends a private message to another player.}}
{{Flink|boolean|is_online|string|desc=Check to see if a player is online.}}
{{Flink|boolean [string]|who_clan|desc=Returns a list of whom is in your clan and if they are in chat.}}

== Time Functions ==
{{Flink|int|gameday_to_int|desc=Returns the current KoL date as an integer.}}
{{Flink|string|gameday_to_string|desc=Returns the current KoL date as a string.}}
{{Flink|int|gametime_to_int|desc=Returns the current KoL time in ms as an integer.}}
{{Flink|string|now_to_string|string|desc=Returns current local time/date in SimpleDateFormat format.}}
{{Flink|string|time_to_string|desc=Returns the current local time in HH:mm:ss z format.}}
{{Flink|string|today_to_string|desc=Returns the current local day in ISO format.}}

== Debugging Functions ==
{{Flink|void|disable|string|desc=Disables the specified function.}}
{{Flink|void|enable|string|desc=Enables the specified function.}}
{{Flink|buffer|load_html|string|desc=Works like visit_url(), but for debugging.}}
{{Flink|string|make_url|string|boolean|boolean|desc=Crafts the URL to visit.}}

== Map Management Functions ==
{{Flink|boolean|file_to_map|string|aggregate|desc=Loads a map from a tab-delimited text file.}}
{{Flink|boolean|map_to_file|aggregate|string|desc=Saves a map to a tab-delimited text file.}}
{{Flink|int|count|aggregate|desc=Returns the number of defined keys for the specified aggregate.}}
{{Flink|void|clear|aggregate|desc=Removes all keys from the specified aggregate.}}

== Other Functions ==
{{Flink|void|abort|{{opt|string}}|desc=Aborts the current script with an optional message.}}
{{Flink|void|print|string|{{opt|string}}|desc=Prints to CLI and status line of Adventuring window, optionally in a specified color.}}
{{Flink|void|print_html|string|desc=Prints to CLI, parsing any included html.}}
{{Flink|void|logprint|string|desc=Prints to the session log.}}
{{Flink|boolean|cli_execute|string|desc=Executes the given command as if it were entered into the CLI.}}
{{Flink|void|wait|int}}
{{Flink|void|waitq|int|desc=Sleeps for the specified number of seconds.}}
{{Flink|boolean|user_confirm|string|desc=Allows user input in Y/N format.}}
{{Flink|string|get_property|string|desc=Gets a global or user preference as appropriate.}}
{{Flink|void|set_property|string|string|desc=Sets a global or user preference as appropriate.}}
{{Flink|void|batch_open|desc=Used to mark the beginning of a block of functions to operate in batch mode (see page for {{f|batch_close}} for details).}}
{{Flink|boolean|batch_close|desc=Used to mark the end of a block of functions to operate in batch mode (see page for details).}}
{{Flink|int|get_revision|desc=Returns the current KoLmafia revision number.}}
{{Flink|string|get_version|desc=Returns the most recent KoLmafia version.}}

Additional functions that are considered not really to be ash functions are available in [[Miscellaneous ASH Features#Special Syntax Functions|Misc ASH Features]]

[[Category:Scripting]]

ASH For Beginners

2011-09-16T15:17:44Z

QVamp: added section on how to run scripts.

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon. Also, every identifier in ASH—variables, functions, and other various keywords—are case-insensitive, so <code>string myVar="abb"</code> and <code>STRing MYvar="abb"</code> produce the same results.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=On the other hand:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variable is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions. Since ASH uses curly brace scope, variables within a set of curly braces ('''{ }''') will not be available outside that same set of braces.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over.

====Built-in functions====
Many functions are built-in to KoLmafia, and examples can be found all over this wiki. Examples on the wiki are given in the following format:

datatypeReturned function_name([datatype1 parameter1] ...)

The first part is the datatype that the function returns. Though you don't have to make use of this in a script, you would almost always want to (except for some functions that return a boolean). You need to be careful to match datatypes (though sometimes an implicit conversion is done; ie KoLmafia will usually translate a float into an int, and many commands that output text will implicitly convert from most datatypes). For example, if you have a variable of the datatype string, it is often an error to assign to it a function that returns an item.

The function name follows and then parentheses, which may have nothing or multiple sets of datatypes & parameters.

The parameter names are used for reference on the rest of the page (so you can match descriptions of parameters to the parameter in question, which is especially useful if the function takes more than one parameter with the same datatype).

Note that, as with assignments of a function's return value, it is important to match the parameter datatypes when using the function. If you have a function with the parameter item it, and you supply the name of the item as text in quotes (which is how a string is written), you will get an error for doing so.

====Custom-coded functions====
It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int()
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"))
</syntaxhighlight>}}

Note that scope (discussed above, under [[ASH_For_Beginners#Variables|Variables]]) also applies to user-defined functions. Also, functions built into KoLmafia have priority over any user-defined functions with the same name and parameters.

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated. For instance: "3x " + $item[Polka Pop] yields "3x Polka Pop".

==Running a Script==
Once your script is saved, you can run it. Scripts saved in the scripts directory will appear in Mafia under the scripts menu. Simply clicking on one will run it. You may also run your script from the command line by typing "exec" followed by the script name For instance: exec myscript.

The script looks for the function 'main()' in order to know where to start.

{{CodeSample|description=Generally the function will look like this:|code=<syntaxhighlight>
void main() {
// the rest of your code
}
</syntaxhighlight>}}

The main function can contain variables, other code and calls to other functions within the script.

You may also have an input into your main function. By requiring an input, this will cause KoLmafia to show a textbox to the user in order to get input into the script. This textbox can be filled in and submitted, or cancelled.

[[Category:Scripting]]

Data Types

2011-09-12T14:44:37Z

QVamp: added missing datatype

{{TOCright}}
==Primitive Datatypes==

===void===
Can be thought of better as the absence of a datatype. No value can be assigned to '''void''' nor can a value be returned from a function of datatype '''void'''.

===boolean===
A boolean value is either '''true''' or '''false'''. By default, a boolean variable is set to false.

===int===

A whole number (short for "integer"), either positive or negative (or 0). The int used by KoLmafia is a 32-bit signed int, meaning it has a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648. The default value of a integer variable is 0.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:
{{
CodeSample|
code=
<syntaxhighlight>
int a = 1;
int b = 2;
print( a / b * 2 );
</syntaxhighlight>}}
Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

===float===

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3]

When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.

Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.
{{
CodeSample|
description=For instance, try the following code as an example of how rather long post-decimal portions are handled:|
code=
<syntaxhighlight>
float f;
f = 4.9999999;
print( f );
</syntaxhighlight>}}
The default value of a <code>float</code> variable is 0.0.

===string===

A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, always enclose the desired value in either single or double quotes (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.{{CodeSample|
description=For example:|
code=
<syntaxhighlight>
string s = "This is my \"friend\" Pete.";
</syntaxhighlight>|
moreinfo=
Will result in the following being stored to s:
<pre>This is my "friend" Pete</pre>}}
The default value of a string is an empty string, or literally <code>""</code>.

===buffer===

Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under [[String Handling Routines#Regular Expressions|Regular Expressions]].)

==Special Datatypes==

Several datatypes are included in KoLmafia to represent common categories within the KoL universe.

Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.
{{CodeSample|
description=For example, to declare an item datatype and assign it a value, you would use the following line of code:|
code=
<syntaxhighlight>
item it = $item[ broken skull ];
</syntaxhighlight>}}
The default values of any variable of one of the following types is <code>$''type''[ none ]</code>. For example, the default value of a <code>item</code> variable is <code>$item[ none ]</code>.

===class===

Besides $class[ none ], there are six possible values for this datatype:

* Seal Clubber
* Turtle Tamer
* Pastamancer
* Sauceror
* Disco Bandit
* Accordion Thief

===coinmaster===
All shops that deal with currency other than meat.

===effect===

Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Effects}} page for more information.

===element===

Besides $element[ none ], there are six possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.)
Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).

* cold
* hot
* sleaze
* spooky
* stench
* slime

===familiar===

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Familiars}} page for more information.

===item===

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.
{{CodeSample|
description=For example, you could assign the item plexiglass pants as follows:|
code=
<syntaxhighlight>
item it = $item[ 1234 ];
</syntaxhighlight>}}
The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Items}} page for more information.

===location===

Any location one can adventure at in KoL is valid for this datatype.

The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Locations}} page for more information.

===monster===

Any monster you can encounter in KoL is valid for this datatype.

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Monster Compendium}} page for more information.

===skill===
Any skill you can have in KoL (whether permable or not, granted by items, etc.) is valid for this datatype.

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Skills}} page for more information.

===slot===

Besides $slot[ none ], there are 13 possible values for this datatype.

* hat
* weapon
* off-hand
* shirt
* pants
* acc1
* acc2
* acc3
* familiar
* sticker1
* sticker2
* sticker3
* fakehand

===stat===

Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).

* muscle
* mysticality
* moxie
* submuscle
* submysticality
* submoxie

==aggregate==

An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see [[Data Structures]].

==record==

Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for [[Data Structures]].

==Plural Typed Constants==

(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:
{{CodeSample|code=<syntaxhighlight>
foreach weapon in $items[star sword, star staff, star crossbow] {
if (available_amount(weapon) > 0) {
equip(weapon);
break;
}
}</syntaxhighlight>}}
The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:
* The list can span multiple lines.
* Whitespace before or after elements is ignored.
* Completely empty elements are ignored (so that you can leave a comma at the end of the list).
* You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
* All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".

The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:
* Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
* There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
* The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.

In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example:
{{CodeSample|code=<syntaxhighlight>
for hour from 1 to 12 {
print("It's " + hour + " o'clock.");
if ($ints[10, 2, 4] contains hour) {
print("Time to drink a Dr Pepper!");
}
}</syntaxhighlight>}}
(Yes, that example could just as easily have been done with a switch statement.)

Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example:
{{CodeSample|code=<syntaxhighlight>
foreach it in $items[] {
if (autosell_price(it) == 42) print(it);
}</syntaxhighlight>}}
Enumeration of all possible values works with the following types:
* $booleans[] - false and true.
* $items[]
* $locations[]
* $classes[]
* $stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
* $skills[]
* $effects[]
* $familiars[]
* $slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
* $monsters[]
* $elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.

The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:
* $ints[] - you don't have enough RAM to store a list with 4 billion elements.
* $floats[] - ditto.
* $strings[] - nobody has that much RAM.

==Custom==

===matcher===

A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function {{f|create_matcher}}, using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see [[Regular Expressions]].

[[Category:Scripting]]

Data Structures

2011-08-10T18:34:32Z

QVamp: added missing aggregate function

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates new_pricelist */

my_pricelist = new_pricelist;
</syntaxhighlight>}}

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
</syntaxhighlight>}}

If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}
<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used (even multidimensional maps, but note that you can only sort along a single dimension at a time). The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(copy-pasted from Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Starting with SVN revision 1311 of KoLmafia, ASH now supports a new kind of structured data: the record. Here is a little example of how you declare a record and variables of the new type you've created by doing so.

{{CodeSample|code=<syntaxhighlight>
record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;
</syntaxhighlight>}}

What I've done with the above is declare a new data type which I've named "my_type". Having declared the new type, I can use it (almost) anywhere that I can use a built-in type name. I declared a variable, "rvar", of that type, and I defined a map, "mrvar", which maps keys of type integer to values of type my_type.

The new type, "my_type" is a "composite" type. It contains four fields. "ifield" is an integer. "sfield" is a string. "rfield" is another composite field: an anonymous record containing two integers named "first" and "second". Finally, "mfield" is a map from [int, int] to int.

As you can see, a record can combine data of all the types ASH supports: primitive, aggregate, and composite.

Having defined the new data type and several variables using it, here are some examples of how to access the fields.

{{CodeSample|code=<syntaxhighlight>
rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.rfield.second = 2000;
rvar.mfield[ 2, 3 ] = 12;

mrvar[ 1 ] = rvar;

foreach key in mrvar
foreach key1, key2 in mrvar[key].mfield
print( "val = " + mrvar[key].mfield[key1,key2] );
</syntaxhighlight>}}

As you can see, if you have a variable that is a record, you access the fields of the record by following the variable name with ".<field name>". The resulting value will be of whatever type you declared in the definition of the record. If the value is a map, you can give a list of keys within [], just like any other map. If the value is another record, you can access the fields of the nested record by using another ".<field name>".

If you are familiar with Pascal "records" or C/C++ "structs", this should all be comfortably familiar.

Finally, if you create a map whose values is a record, the file_to_map and map_to_file built-in ASH functions will Do The Right Thing; they will efficiently and reliably save and restore your data.

[[Category:Scripting]]