BetterShop - The "better" global command-based shop that ties into iConomy

active developer: jascotty2 
initial idea & programing by jjfs85
with additional coding contributions by: lologarithm, dhatch
===============================================================================
In-Game Commands:
===============================================================================

/shop 				<command>		for those used to a plugin having one command, this is another way to get to the following (also used for some admin commands)
/shop ver[sion] 					shows version # and if is up-to-date
/shop backup						backup the database to a csv file
/shop import 			<file> 			insert values from file in plugin folder
/shop restore 			<file> 			clear shop & load from saved backup file
/shop restock						manually update stock (if enabled)
/shop update 						OP-only command that forces update & restarts server plugins
/shop region define		<name>			uses the player's WorldEdit selection to define a shop region
/shop region remove		<name>			remove a region definition
/shop region list		[page]			list current regions
/shop chest define					set the chest in the crosshairs to a shop chest
/shop chest edit					open the shop chest for editing
/shop chest remove					remove the chest shop status
/shophelp (shelp)		[command]		shows you all the commands you can use, or more help on [command]
/shoplist (sl,slist)		[pagenum]		shows a listing of items for sale (if -1, all, or full given, will show full list. (for console use))
/shopitems (sitems)					show full listing of items in shop, without prices
/shopcheck (sc,scheck) 		<item> [amount]		lookup a specific item so you don't have to read through pages of prices
/shopbuy (buy,sbuy) 		<item> [amount]		buy an item for the price in the shopshop ("all" is accepted as an amount)
/shopbuyall (buyall,sbuyall) 	<item> 			buy all of an item that you can hold
/shopsell (sell,ssell)   	<item> [amount]		sell an item for the price in the shop
/shopadd (sadd): 		<item> <buy> [sell]	add an item to or update an item in the price list
/shopremove (sremove)		<item>			remove an item from the price list
/shopload (sload)					reload prices from pricelist database
/shopsellall (sellall)		[inv] [item [...]]	Sell all of item from your inventory (alias to command /shop sell all) (inv will not search lower 9 slots)
/shopbuystack (buystack)	<item> [item | amount]	buy a stack of an item (usually 64)
/shopsellstack (sellstack)  	<item> [item | amount]	sell a stack of an item (usually 64)
/shopbuyagain (buyagain,sba) 				repeat last buy action
/shopsellagain (sellagain,ssa) 				repeat last sell action
/shopkits (skits)					show a listing of available kits (will be elaborated later)
/shop alias 			<item>			show the itemname, with a list of aliases


===============================================================================
Features:
===============================================================================

=== plugin support
currently dependent on 
- iConomy		http://dev.bukkit.org/server-mods/iconomy/
--or
- BOSeconomy  	http://dev.bukkit.org/server-mods/boseconomy/
-- or
- MultiCurrency http://forums.bukkit.org/threads/26455/
--or
- Essentials	http://dev.bukkit.org/server-mods/essentials/
--or
- 3co			http://forums.bukkit.org/threads/22461/
also supports: 
Permissions 	http://forums.bukkit.org/threads/18430/
Help 			http://forums.bukkit.org/threads/13601/
MinecraftIM 	http://dev.bukkit.org/server-mods/minecraftim/
Spout 			http://dev.bukkit.org/server-mods/spout/

=== configurable
Fully configurable colors and message text in config.yml file
shoplist can have text alignment (read config for more info): <item> <l(eft-aligned)> <buy and sell info>
- uses minecraft font character spacing, so is very close to perfectly aligned in chat
shoplist can optionally not show listing tail (or head, but recommended to leave <page> of <pages>)
Items can be colored in the new itemsdb.yml file
also in itemsdb.yml: kits!
- define your own kits that the shop can sell
- three examples provided, edit and add to your liking
Configurable Options:
-max pagesize when printing shoplist
-whether to broadcast all transactions publicly
-name of the pricelist file/table
-customsort: a custom sorting order, so you can have items at the top of the shop list
-allowbuyillegal: if someone without BetterShop.admin.illegal can buy illegal items
-whether maxstack should be honored
-if used tools can be bought back
-default color for items

=== shop flexibility
shopcheck will run a name comparison check, and return all matching items
Item sub-type support for dye colors, cloth colors, etc: magentacloth = 35:2 = cloth:magenta
"all" is a valid amount when buying or selling: "/sell cobblestone all" or "/sell all cobblestone"
damaged tools can be resold for an adjusted value of sellprice*(1-(damage/maxdamage))
buystack can be given multiple items, or number of stacks: "/buystack wool 5" or "/buystack wool blackdye reddye"
shopsellall can be given multiple items (/sell all cobble gravel flint dirt)
plural-insensitive items: if not found, will check if plural & remove "s"
not just items can be bought anymore: can now buy LivingEntities, like dogs (wolf)
item categories
- can search for items by category (in shoplist)
signs can be used for buying & selling
- first line: [BetterShop] (not case-sensitive)
- second line: action: buy [amt], buyall, buystack, sell [amt], sellall, sellstack
- third line: item (name, id, etc)
- fourth line: unused (was going to make price, but decided on pricecheck instead)
- to activate, someone with BetterShop.admin.makesign must left-click the sign.. the first line will change color when active
- left-click for price check (or activate), right-click to buy/sell
- if a unauthorized player destroys a block a sign is on, is canceled
chests can also be used as a shop interface
- to define a chest, point at the chest & type "/shop chest define"
- automatically detects double-chests
- multiple users can use the same chest shop
- - each user gets a customized chest screen
- - items in the display show either max stack, or max of that item the user can afford
players using Spout (if installed & enabled) can use a GUI Menu for buying & selling
- default button is 'b'
- displays items in shop in top half
- item detail below with # in stock, buy/sell price, & buttons to buy & sell
- amount to buy/sell can be set in text box or with up/down buttons
- item categories can also be used in the display


=== administration
Every item and subtype can be priced differently
Disable buying or selling of an item by giving it a price of -1	 (0 makes it free)
command aliases to stop carpal tunnel
many commands have sub-aliases.. eg. shoplist kits will run shoplistkits
MySQL pricelist support 
MySQL pricelist can be cached for a given timespan (decreases table selects) (flatfile is cached until manually updated)
Transaction records (MySQL or flatfile as .csv)
Downloads mysql-bin.jar dependency automatically
buy/sell cap in program set to 999,999,999 (not that you'd be using that much, but the cap is to prevent other errors)
if encounters errors while editing a player's account, will attempt to reload iConomy (i've had issuses with it before)
can backup the current pricelist: /shop backup
can restore from backup: /shop restore <file>
can import new prices in a batch from a csv (or old yml format) : /shop import <file>
on start, can check the download page to see if there is an update available
shop can be given a finite stock from which to buy & sell
/shop ver[sion] to check the current version & see if there's an update
/shop update to manually download & install the most recent version
MinecraftIM support: forward errors or all messages
checks for missing & unused configuration nodes
strings have default values if missing
auto error reporting added (can be disabled)
custom message you can send with the error report
help main page integration can be disabled
global shop can be disabled & only allow signs to be used
can use permissions to define discounts for certain users
- uses nodes in "BetterShop.discount.xxxx"
- nodes defined in config under discountGroups
- ex: discountGroups:
          VIP: 10   # gives 10% discount to players with BetterShop.discount.VIP
support for bukkit permissions
- built-in support for "BetterShop.(user|admin).*" nodes, so you don't have to add all of the other nodes


There are two ways to add things to the shop:
Recommended, but slow: use /shopadd [item] [buy-price] [sell-price]
Faster: use a text editor (or spreadsheet program) to add items to the BetterShop.csv file. 
	items are in this order: id, subdata, buy, sell, name
	item id & subdata are checked against itemsdb.yml, and are removed if they don't exist
	for your convenience, you can use item names (not subitem names, though), so "wool,blue,1,-1" is a valid entry
	The name value is there only for human readability, it's not read by the plugin.

===============================================================================
Permissions:
===============================================================================
Just add the following nodes to Permissions' config.yml file (or data.yml file for GroupManager):

BetterShop.user.*	Allows the user to use the list, sell, buy, and help commands
BetterShop.admin.*	Allows the user to use the add, remove, and load commands

There are other nodes that allow only more specific permissions, but I recommend using the above.

BetterShop.user.list		look through shop listing of prices
BetterShop.user.check		check the price of item(s)
BetterShop.user.help		view ingame help menu
BetterShop.user.buy			buy items from the shop
BetterShop.user.sell		sell items to the shop
BetterShop.user.spout		for spout screen access
BetterShop.user.chest		allow a user to use the a chest shop
BetterShop.admin.add		add/edit items to/in the shop
BetterShop.admin.remove		remove items from the shop
BetterShop.admin.load		reload configuration & pricelist
BetterShop.admin.info		show shop stats (only version number right now)
BetterShop.admin.illegal	gives the ability to purchase 'illegal' items
BetterShop.admin.backup		backing up and restoring the pricelist
BetterShop.admin.restock	manually restock (if item stock is enabled)
BetterShop.admin.makesign	make/remove a bettershop sign
BetterShop.admin.region		define/remove shop regions
BetterShop.admin.chests		define/remove chest shops

===============================================================================
TODO (items are removed as they're added)
===============================================================================

calculated/derived item prices
/shopvalue item[@amount] item  	to show the current trade value for two items
dynamic market pricing, based off of logged market activity
add option for amount in stock for surplus decreases how much item is worth to the shop
add pages for /shopitems
more descriptive kit listing, similar to shoplist:
- pages
- show what makes up a kit
- enable admin.add to see available kits
SQLite support?
tie item prices to stock quotes?
craftables' stock is tied to source material stock (if using sell craftables)
make LivingEntities follow the owner around?
change buystock if itemStock is enabled so that if trying to buy multiple stacks (buystack item 20) and stock runs out to stop buying (stop showing "out of stock")
individually-customizable restock stock values per-item
automatically add missing config nodes (preserving comments) when upgrading
add a simple builtin economy system, if none found?
user-owned shops (signs, linked to chests?) ?
daily profit caps for selling to the shop
multiple shop definitions for various regions?


=== Removed (not going to implement)
persistentMySQL: if false, will disconnect from db when now using it (use if have a high cacheUpdate)
		(the MySQL connection is now shared with other features, so disonnecting could cause more performance issues)
dynamicDiscount: if a user has an applicable discount, will also discount items crafted using discount
		(if i do implement discounts, this will be automatic)
Cookies	integration:  http://forums.bukkit.org/threads/5327/
		(might implement if becomes active again)
items as currency (if no economy plugin)
		(as i began to write this, i realized that it's an entire economy plugin... one that i just might develop)