gistfile1.txt

## Coding 1-2-3
# This tutorial assumes you're using Ruby 1.8+
#
# http://rubyonrails.org/download
#
# Pick up a free text-editor like SciTE for Windows or 
# TextWrangler for Mac
# Windows: http://bit.ly/SciTE  
# Mac: http://bit.ly/textwrangler
#
# The raw textfile from which this tutorial snippet was generated
# can be found here: https://gist.github.com/845131
#
# To **do** this tutorial, all you need to do is open up 
# your text-editor, type in some code, and:
# Windows, SciTE: hit F5
# Mac, TextWrangler: 

#### Say Hello

# The traditional first line of code. You just did a lot there. 
puts "Hello world!"
# Take a look how this is done in other languages:
# http://bit.ly/helloworldcode
#
# Languages like Ruby and Python make it easy to get
# into getting things done
#

#### The Method
# The first word in that code is **puts**
#
#
# This is what's called a **method** in Ruby (also referred to as 
# a function in other languages). 
# It is short-hand for "print"; in this case, it's printing to your screen.
#

#### The String
# That "Hello world!" is two words; in our code, it's basically one thing: a String
# Strings are used to hold characters, whether it be 
# a single word or an entire book
puts "Four score and seven years ago our fathers 
brought forth on this continent, a new nation, 
conceived in Liberty, and dedicated to the proposition 
that all men are created equal."
#
# Quotation marks, single or double, signifies the beginning and end of a string
puts 'Hello, "world"'
puts "'Allo, world"

# How would you use double-quotes inside double-quotes, for instance, when 
# trying to describe someone speaking? Use the backslash \ character.
puts "That fellow said, \"Hello World\""
# You will use the backslash frequently, as it is how we signify in our code
# that the following character is special. In this case, we want the quotation
# mark to not be treated like a normal quotation mark, which would prematurely
# end our sentence.

#### Variables
# Think of these as pointers, or labels of actual values.
hello_world = "Hello, World"
puts hello_world
# They don't exist until you declare them. You can name them
# just about anything you want with alphanumeric characters, 
# and as long as they aren't # words already special to Ruby, 
# like **if** or **end**. 
# To be safe, let's just use lowercase alphabetical characters
# and underscores
one_plus_one = 3
puts one_plus_one

# You can see that the **equals sign, =**,  is used to assign values.
#
# And that's about as much introduction as we need to actually do something

#### What's to do in this town?
# Go to your browser and open this address:
# http://maps.googleapis.com/maps/api/geocode/xml?address=raleigh+NC&sensor=false
#
# If you saw something like this, with our without tags...
#
# <?xml version="1.0" encoding="UTF-8"?> <GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component>...

#
# ...then you've just used Google's Geocoding API
# You can read the details here:
# http://code.google.com/apis/maps/documentation/geocoding/
#
##### The API
# Let's look at the structure of that url real quick:
#
###### http://maps.googleapis.com/maps/api/geocode/xml
#
# This is the **address** of the site where it exists on the Internets 
#
###### ?
#
# This **question mark** signifies the end of the address and the beginning of the 
# parameters that we use to tell Google what exactly we want
# 
###### address=raleigh+NC
#
# This is the first **key-value pair** of parameters. The **key** in this case is
# "address". The **value**, i.e. the address we're interested in, is "raleigh+NC". The plus-sign is just how we signify a space-character for the URL.
#
#
###### &sensor=false
# The other key-value pair here is **sensor=false** and is just a parameter that Google requires. But notice the **ampersand**. That is what delimites the different key-value pairs in a request string.

##### Back to Strings and Variables
# OK, back to coding. Let's put the address into a variable
my_address='Raleigh+NC'
# 
# We're going to use a new String trick to manage the url:
the_url = "http://maps.googleapis.com/maps/api/geocode/xml?sensor=false&address="+my_address
#
# As you can guess, that **plus sign** adds the value of **my_address** to 
# the variable **the_url**. Notice how the order of paramaters for Google's API
# is not important
#
# But if you like order, you could also do this:
#
the_url = "http://maps.googleapis.com/maps/api/geocode/xml?address="+my_address+"&sensor=false"

# It works, but this is not considered particularly elegant. For most situations, we'd rather do this:
#
the_url = "http://maps.googleapis.com/maps/api/geocode/xml?address=#{my_address}&sensor=false"
#
# We'll be using this trick later. Basically, what's inside the **#{}** gets interpreted and output as a string; in this case, the value of **my_address**. If you didn't have the pound-sign-and-curly-brackets around **my_address**, you'd be asking Google's API for the the geocoding information of "my_address," which would just be silly.
#
# Mess around with **puts** to see when you change the value of **my_address** and
# reassign the value to **the_url**. Or when you remove the curly-brackets
#
# Also to do this the string **must be in double-quotes**
#
#
##### The Call, in Code
#
# OK finally, we're going to do something. After we do this:
require 'open-uri'
#
# Why is programming "easy," relatively speaking? Because other programmers
# have done the hard work of making libraries of code and methods that they've
# wrapped up in a single word. With **require** we've called up a library
# that makes retrieving web-files as easy as this:
# (you did set **my_address** and **the_url**, right?)
google_result = open(the_url)
puts google_result.read
#
# You should see the XML you got when visiting the API through your browser.
# Ta-da, that's kind of useful...
#
# A few notes before moving on:
# 1. The google_result variable is not in itself a string. If you try **puts** sans
# the read:
puts google_result
# You get #<StringIO:0x10063ade8>
#
# It's not just a string, it's something called a StringIO. For now, we just
# care about the contents, which can be read through a method called **read**
# 
# If you really care what makes up StringIO, require the 'pp' library and do:
#
require 'pp'
pp google_result
#

#### That Dot
# One more very important thing: You probably noticed the **dot** we used
# in **google_result.read**. Basically, the **dot** calls the method **read**
# which belongs to **google_result** (**read** is one of those things that **StringIO** has that **String** does not)
#
# **google_result** is referred to as the method's **receiver**. That's just
# some lingo. All methods in Ruby have a **receiver**. 


# Sidenote: What is the receiver of **open** and **puts**? Something called the
# **Kernel**. If you wanted to be verbose, you could do:
#
Kernel.puts "I AM THE RECEIVER, SAYS KERNEL"
# And when you **require 'open-uri'**, you're giving the Kernel the **open**
# method. Not doing that **require** and trying to call **open** would
# give you an error message
#
# BTW, if you thought the code above was complicated, try looking at 
# what's behind [**open-uri**](http://www.ruby-doc.org/stdlib/libdoc/open-uri/rdoc/index.html) and 
# seeing what you got to skip past. Heck, look at the code behind [**puts**](http://www.ruby-doc.org/core/classes/Kernel.src/M001403.html)
#
#

#### FourSquare API
#
# Enough theory lecture, let's make use of our data
#
# Let's store whatever you got for latitude and longitude
# into variables. There's several lat/long pairs in the xml,
# but either pair is fine. Ideally, you want the pair nested
# in between the <location> tags
#
my_lat = 37.421622
my_lng = -122.084026

# Let's take a look at the (old) [Foursquare API](http://groups.google.com/group/foursquare-api/web/api-documentation)
# 
# http://api.foursquare.com/v1/tips?geolat=&geolong=-&filter=nearby
#
# This is the API call for **nearby tips**. You can see that the **tips** is part of the address and **filter** specifies the...filter...i.e. we want tips near us.
#
# Now we just have to give it the lat/long coordinates to search nearby. 
#
# Let's use that string trick with the **curly brackets**:

fsquare_url="http://api.foursquare.com/v1/tips?geolat=#{my_lat}&geolong=#{my_lng}&filter=nearby"
#
##### Calling FourSquare
#
# Let's make the call
fsquare_result = open(fsquare_url)

# If you were successful, and depending what coordinates you used, you should've
# gotten back a big XML relating to tips.
#