--- /dev/null
+ API for the new dispense
+-------------------------
+
+New dispense is written in entirely in postgresql. The server does all the
+required processing, meaning that database integrity is always maintained.
+
+The current interface for dispense is using a postgresql client library.
+Client libraries exist for many languages including C, C++, Perl, Python,
+Ruby, PHP, or you could also speak with the supplied client 'psql' through
+stdin/stdout.
+
+The details for connecting to the database are:
+ hostname: dispense.ucc.gu.uwa.edu.au
+ username: anondispense
+ database: dispense
+
+No password is required. You will only be able to connect from 'trusted'
+machines - currently this is mussel, mermaid, morwong.
+
+Note the API still isn't stable - it'd be worth running these commands by hand
+to see what the resulting tables look like.
+
+The useful things can be done once connected:
+
+ - SELECT * FROM get_services(username)
+ will give you a list of services available to the given user, including
+ syntax if parameters are required
+ - SELECT get_balance()
+ will return a table of all users and their balances.
+ - SELECT get_balance(username)
+ will return a table with one row for the given user, displaying their
+ account balance.
+ - SELECT do_request(target_user, service_name, parameters)
+ will perform a request.
+ * target_user is the user you wish to perform the request upon.
+ You will only be permitted to act on somebody else if you are in the
+ coke group.
+ * service_name is the name of the service as seen in the services
+ table.
+ * parameters is an array of parameters for the service, if required.
+ These should appear in the order as item_syntax from the services
+ table.
+
+Example follows:
+
+$ psql dispense -U anondispense -h dispense.ucc.gu.uwa.edu.au
+\Welcome to psql 7.4.1, the PostgreSQL interactive terminal.
+
+Type: \copyright for distribution terms
+ \h for help with SQL commands
+ \? for help on internal slash commands
+ \g or terminate with semicolon to execute query
+ \q to quit
+
+-- Equivalent of bringing up the menu. Only items allowed for
+-- the given user are shown.
+dispense=> select * from get_services('dagobah');
+ item_name | item_cost_cents | item_syntax | item_stock
+-------------+-----------------+--------------------------------------+------------
+ nothing | | |
+ give | | <username> <cents> |
+ acct | | <cents> <reason> |
+ passion pop | 80 | | 8
+ vb | 80 | | 0
+ emu export | 80 | | 3
+ champagne | 80 | | 9
+ coke powder | 80 | | 11
+ update_coke | | <slot number> <new name> <new price> |
+ opendoor | | |
+ grape juice | 80 | | 0
+ some foo | 77 | | 3
+(12 rows)
+
+-- Get balance for a user.
+-- Equivalent of 'dispense acct dagobah'
+-- Calling just get_balance() will return all users balances.
+dispense=> select * from get_balance('dagobah');
+ user_name | user_balance_cents | user_balance_bytes
+-----------+--------------------+--------------------
+ dagobah | -5080 | 0
+(1 row)
+
+-- Dispense something for a user.
+-- Equivalent of 'dispense -u dagobah grape juice'
+dispense=> select do_request('dagobah', 'grape juice', NULL);
+ERROR: You may not dispense below -$20.00.
+CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement
+
+-- Adjust somebody's account balance up or down.
+-- Equivalent of 'dispense acct dagobah +10000 BAG123'
+dispense=> select do_request('dagobah', 'acct', array['+10000', 'BAG123']);
+ do_request
+------------
+ t
+(1 row)
+
+-- Get the balance once again ... note that it's higher :)
+dispense=> select * from get_balance('dagobah');
+ user_name | user_balance_cents | user_balance_bytes
+-----------+--------------------+--------------------
+ dagobah | 4920 | 0
+(1 row)
+
+-- Try that dispense again, but we see there is none
+dispense=> select do_request('dagobah', 'grape juice', NULL);
+ERROR: We are out of stock of that item.
+CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement
+
+-- Try that dispense again, but we see there is none
+dispense=> select do_request('dagobah', 'some foo', NULL);
+ do_request
+------------
+ t
+(1 row)
+
+-- Updating a slot name/price on the coke machine
+dispense=> select do_request('dagobah', 'update_coke', array['3', 'orange blah', '88']);
+ do_request
+------------
+ t
+(1 row)
+
+-- Note the services have changed
+dispense=> select * from get_services('dagobah');
+ item_name | item_cost_cents | item_syntax | item_stock
+-------------+-----------------+--------------------------------------+------------
+ nothing | | |
+ give | | <username> <cents> |
+ acct | | <cents> <reason> |
+ passion pop | 80 | | 8
+ vb | 80 | | 0
+ emu export | 80 | | 3
+ champagne | 80 | | 9
+ coke powder | 80 | | 11
+ update_coke | | <slot number> <new name> <new price> |
+ opendoor | | |
+ grape juice | 80 | | 0
+ orange blah | 88 | | 3
+(12 rows)
+
git.ucc.asn.au / zanchey / dispense2.git / blobdiff
UCC git Repository :: git.ucc.asn.au