expand custom price function docs

README.md

@@ -1,3 +1,132 @@
-# TradeSkillMaster
+# TradeSkillMaster (Ascension.gg)
 
-This is the repository for Trade Skill Master (TSM). Modified for Ascension.gg. 
+TradeSkillMaster (TSM) is a World of Warcraft addon suite. This fork is tailored for Ascension.gg and includes the core addon plus feature modules.
+
+## Modules
+Each module lives in its own top-level folder and is loaded by its `.toc` manifest:
+- `TradeSkillMaster` (core)
+- `TradeSkillMaster_Accounting`
+- `TradeSkillMaster_AuctionDB`
+- `TradeSkillMaster_Auctioning`
+- `TradeSkillMaster_Crafting`
+- `TradeSkillMaster_Destroying`
+- `TradeSkillMaster_ItemTracker`
+- `TradeSkillMaster_Mailing`
+- `TradeSkillMaster_Shopping`
+- `TradeSkillMaster_Warehousing`
+
+## Install (Local)
+Copy the desired module folders into your AddOns directory and reload the game:
+- AddOns: `/home/zalox/Games/ascension-wow/drive_c/Program Files/Ascension Launcher/resources/client/Interface/AddOns`
+- SavedVariables: `/home/zalox/Games/ascension-wow/drive_c/Program Files/Ascension Launcher/resources/client/WTF/Account/omanfred/SavedVariables`
+
+In-game, use `/reload` after changes.
+
+## Development Notes
+- Lua files use tab indentation.
+- Keep `.toc` and primary `.lua` filenames aligned with the module name.
+- If adding files, list them in the module `.toc`.
+- Versions are tracked in `TradeSkillMaster/TradeSkillMaster.toc` and `TradeSkillMaster_AuctionDB/TradeSkillMaster_AuctionDB.toc`.
+
+## Custom Price Sources (Full Reference)
+TSM price strings can reference built-in data sources and combine them with math. Source names are case-insensitive.
+
+### Core sources
+- `VendorBuy`: Buy from vendor.
+- `VendorSell`: Sell to vendor.
+- `Disenchant`: Disenchant value (if available).
+
+### AuctionDB sources
+- `DBMarket`: AuctionDB market value (scan/app historical average).
+- `DBMinBuyout`: AuctionDB minimum buyout from the most recent scan data.
+
+### Accounting sources
+- `avgSell`: Average sell price.
+- `avgBuy`: Average buy price.
+- `maxSell`: Maximum sell price.
+- `maxBuy`: Maximum buy price.
+- `minSell`: Minimum sell price.
+- `minBuy`: Minimum buy price.
+
+### Crafting sources
+- `Crafting`: Crafting cost.
+- `matPrice`: Crafting material cost.
+
+### Optional addon sources
+Available only if the addon is installed and enabled.
+- `AucAppraiser`: Auctioneer - Appraiser.
+- `AucMinBuyout`: Auctioneer - Minimum Buyout.
+- `AucMarket`: Auctioneer - Market Value.
+- `AtrValue`: Auctionator - Auction Value.
+
+### Functions and syntax
+- Math operators: `+`, `-`, `*`, `/`, `^`
+- Money literals: `100g`, `50s`, `25c`, or combined `12g 34s 56c`
+- Convert another item: `convert(priceSource, itemLink)` or `convert(priceSource, item:12345)`
+
+### Function: min(...)
+Returns the smallest of the provided values. Ignores invalid values.
+Example: `min(dbmarket, 250g)`
+
+### Function: max(...)
+Returns the largest of the provided values. Ignores invalid values.
+Example: `max(dbminbuyout, 100g)`
+
+### Function: avg(...)
+Returns the average (rounded) of the provided values. Ignores invalid values.
+Example: `avg(dbmarket, dbminbuyout)`
+
+### Function: first(...)
+Returns the first valid value from left to right.
+Example: `first(dbminbuyout, dbmarket, 100g)`
+
+### Function: check(checkValue, ifValue, elseValue)
+Returns `ifValue` when `checkValue` is greater than 0, otherwise `elseValue`.
+Example: `check(dbminbuyout, dbminbuyout, dbmarket)`
+
+### Function: ifgt(a, b, ifValue, elseValue)
+Returns `ifValue` when `a` is greater than `b`, otherwise `elseValue`.
+Example: `ifgt(dbminbuyout, 200g, dbminbuyout, dbmarket)`
+
+### Function: ifgte(a, b, ifValue, elseValue)
+Returns `ifValue` when `a` is greater than or equal to `b`, otherwise `elseValue`.
+Example: `ifgte(dbmarket, 500g, 500g, dbmarket)`
+
+### Function: iflt(a, b, ifValue, elseValue)
+Returns `ifValue` when `a` is less than `b`, otherwise `elseValue`.
+Example: `iflt(dbminbuyout, 50g, 50g, dbminbuyout)`
+
+### Function: iflte(a, b, ifValue, elseValue)
+Returns `ifValue` when `a` is less than or equal to `b`, otherwise `elseValue`.
+Example: `iflte(dbmarket, 20g, dbmarket, 20g)`
+
+### Function: ifeq(a, b, ifValue, elseValue)
+Returns `ifValue` when `a` equals `b`, otherwise `elseValue`.
+Example: `ifeq(dbminbuyout, dbmarket, dbminbuyout, dbmarket)`
+
+### Function: round(value[, step])
+Rounds to the nearest `step` (default `1`).
+Example: `round(dbmarket, 1g)`
+
+### Function: roundup(value[, step])
+Rounds up to the nearest `step` (default `1`).
+Example: `roundup(dbmarket, 5g)`
+
+### Function: rounddown(value[, step])
+Rounds down to the nearest `step` (default `1`).
+Example: `rounddown(dbmarket, 5g)`
+
+### Examples
+- `dbmarket * 0.9` (90% of market value)
+- `max(dbminbuyout, 100g)` (at least 100g)
+- `min(dbmarket, 250g)` (cap at 250g)
+- `ifgt(dbminbuyout, 200g, dbminbuyout, dbmarket)` (prefer min buyout if above 200g)
+
+Notes:
+- Sources return values only when their module has data (for example, no AuctionDB scan means empty values).
+- Use `DBMarket` for stable pricing and `DBMinBuyout` for recent lows.
+
+## Testing
+There is no automated test framework. Validate changes in-game by:
+1. Logging in / reloading to verify module initialization.
+2. Exercising the relevant UI workflows.

TradeSkillMaster/TradeSkillMaster.toc

@@ -2,7 +2,7 @@
 ## Title: |cff00fe00TradeSkillMaster: Revived|r
 ## Notes: Core addon for the TradeSkillMaster suite, revived for Wrath of the Lich King. Does nothing without modules installed.
 ## Author: Sapu94, Bart39, Gnomezilla [Warmane-Icecrown(A)], BlueAo [Warmane], andrew6180, Yoshiyuka, DimaSheiko, and other contributors...
-## Version: 2.3.13
+## Version: 2.3.15
 ## SavedVariables: TradeSkillMasterAppDB, AscensionTSMDB
 ## OptionalDeps: AccurateTime, Ace3, LibDataBroker-1.1, LibDBIcon-1.0, LibExtraTip, TipHelper, LibParse, LibCompress, LibGraph-2.0, SharedMedia, TheUndermineJournal, TheUndermineJournalGE
 ## X-Embeds: AccurateTime, Ace3, LibDataBroker-1.1, LibDBIcon-1.0, LibExtraTip, TipHelper, LibParse, LibCompress, LibGraph-2.0

TradeSkillMaster_AuctionDB/TradeSkillMaster_AuctionDB.toc

@@ -2,10 +2,10 @@
 ## Title: |cff00ff00TradeSkillMaster_AuctionDB|r
 ## Notes: Stores auction house data and calculates market prices.
 ## Author: Sapu94, Bart39
-## Version: 2.3.13
+## Version: 2.3.15
 ## SavedVariables: AscensionTSM_AuctionDB
 ## Dependency: TradeSkillMaster
-## X-Curse-Packaged-Version: 2.3.13
+## X-Curse-Packaged-Version: 2.3.15
 ## X-Curse-Project-Name: TradeSkillMaster_AuctionDB
 ## X-Curse-Project-ID: tradeskillmaster_auctiondb
 ## X-Curse-Repository-ID: wow/tradeskillmaster_auctiondb/mainline