PyTeladventure
				 ==============

This is an interactive, phone-based, adventure game.  It's written in Python
using Flask and Twilio.

It's based on https://github.com/jjinux/teladventure which is the same
application, written in Ruby on Rails.  The number for that application is
(888) 877-7418.

Phone number: Nothing permanent
Running websites: Nothing permanent
Source code: https://github.com/jjinux/pyteladventure

Installation
============

If you're using Ubuntu:

    $ sudo apt-get install python-virtualenv
    $ sudo apt-get install build-essential
    $ sudo apt-get install python-dev
    $ sudo apt-get install libxml2-dev libxslt-dev

If you're using OS X 10.6:

    Install XCode.

    $ sudo easy_install-2.6 virtualenv

    # See: http://stackoverflow.com/questions/5256397/python-easy-install-fails-with-assembler-for-architecture-ppc-not-installed-on
    $ export ARCHFLAGS="-arch i386 -arch x86_64"

Execute the rest of this as your normal user from within this directory:

    $ rm -rf env
    $ virtualenv env
    $ bash  # If you're not already in Bash.
    $ . env/bin/activate
    $ pip install Flask==0.6.1
    $ pip install lettuce==0.1.21
    $ pip install nose==1.0.0
    $ pip install lxml==2.3

Running
=======

Setup the virtualenv environment:

    $ bash  # If you're not already running Bash.
    $ . env/bin/activate

If you haven't already setup the schema, do so by running the following in a
Python shell (make sure you already setup virtualenv):

    $ python
    >>> from pyteladventure import init_db
    >>> init_db()

Now, start the server:

    $ python runserver.py

Running Tests
=============

Setup the virtualenv environment and then run:

    $ lettuce

Hacking
=======

The entry point to the code is pyteladventure/__init__.py.  No, it's not an
empty file.  The tests are in the features directory.  It may help if you
refer to the documentation for Flask, Lettuce, and Twilio.

In that same file, you should turn on DEBUG while developing.  However, make
sure you turn it off in production because it's a security hole.

Also, you may want to alter the SECRET_KEY in that file if you ever put this
on a real server.

Setting Up an SSH Tunnel
========================

It's helpful to setup an ssh tunnel so that you can develop the application
locally and still access it via Twilio.  I happen to have an account on
staging.24hrdiner.com.  Here's how I setup the tunnel:

    $ ssh -R \*:5500:127.0.0.1:5000 jj@staging.24hrdiner.com

You can check that the tunnel is working by going to:
http://staging.24hrdiner.com:5500.

TODO
====

 * Build a website and show the tree graphically.
 * Give more help when creating or editing nodes.
 * Make it possible to skip the story.
 * Get a non-toll-free number for Europeans.
 * Test coverage.
 * Figure out the right voice in the feature file.  Who am I?
 * Acknowledge Abraham who gave me the idea.

Headaches I Encountered
=======================

 * In my tests, I was trying to do world.app.post using a full URL that my
   app had generated in some XML.  However, Werkzeug always returned a 404.
   I couldn't get rid of the 404 until I stripped off the scheme and the netloc
   from the URL.  That's a bug as far as I'm concerned.

 * request.form only contains PUT or POST data.  It doesn't include query
   string parameters.  This surprised me and I spent an hour debugging.
   If you want both query string parameters as well as form parameters, use
   request.values.

 * I forgot that closures and loops don't get along.  See model.py.

 * Lettuce doesn't automatically put ^ and $ in the regexes it suggests.
   This lead to the wrong regex matching because I had one regex that was
   a prefix of another one.