+++ /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)
-