gopher2000 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.2-head@gopherpedia

data/Gemfile

@@ -0,0 +1,27 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in gopher.gemspec
+gemspec
+
+gem "rake"
+gem "logging"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'simplecov', :require => false, :group => :test
+
+  gem "shoulda", ">= 0"
+  gem "rspec"
+
+  gem "bundler", "~> 1.0.0"
+  gem "watchr"
+
+  # There's a god example script stashed away in the repo
+  gem "god"
+
+  #
+  # gems used in examples and for development.
+  #
+  gem "weather-underground"
+end

data/LICENSE.txt

@@ -0,0 +1,14 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.
+

data/README.markdown

@@ -0,0 +1,344 @@
+It's...
+
+	 _____             _                 _____  _____  _____  _____
+    |  __ \           | |               / __  \|  _  ||  _  ||  _  |
+    | |  \/ ___  _ __ | |__   ___ _ __  `' / /'| |/' || |/' || |/' |
+    | | __ / _ \| '_ \| '_ \ / _ \ '__|   / /  |  /| ||  /| ||  /| |
+    | |_\ \ (_) | |_) | | | |  __/ |    ./ /___\ |_/ /\ |_/ /\ |_/ /
+     \____/\___/| .__/|_| |_|\___|_|    \_____/ \___/  \___/  \___/
+                | |
+                |_|
+
+
+Gopher2000 - A Gopher server for the next millenium
+===================================================
+
+Gopher2000 is a ruby-based Gopher server. It is built for speedy, enjoyable development of
+all sorts of gopher sites.
+
+Features
+--------
+* Simple, Sintra-inspired routing DSL.
+* Dynamic requests via named parameters on request paths.
+* built on Event Machine.
+* Easy to mount directories and serve up files.
+* built in logging and stats.
+* Runs on Ruby 1.9.2 with all the modern conveniences.
+
+Requirements
+------------
+* Ruby 1.9.2 or greater
+* Nerves of steel
+
+Examples
+--------
+
+Writing a functional Gopher app is as simple as:
+
+```rb
+route '/simple' do
+	"hi" # You can output any text you want here
+end
+```
+
+
+Or, if you want to provide more interactivity, you can do something like:
+
+```rb
+route '/' do
+  render :index
+end
+
+menu :index do
+  # output a text entry in the menu
+  text 'simple gopher example'
+
+  # use br(x) to add x space between lines
+  br(2)
+
+  # link somewhere
+  link 'current time', '/time'
+  br
+end
+
+route '/time' do
+  "It is currently #{Time.now}"
+end
+```
+
+You can see more working examples in the examples/ folder
+
+Running a script
+----------------
+
+You can use the supplied wrapper script
+
+```
+gopher2000 -d examples/simple.rb
+
+==> *start server at 0.0.0.0 7070*
+```
+
+Or, if you include gopher in your file, you can just run the script itself:
+
+```rb
+# scriptname.rb
+require 'gopher2000'
+
+# ...
+# write some code here
+# ...
+
+# Then, run 'ruby scriptname.rb'
+
+==> *start server at 0.0.0.0 7070*
+```
+There are several command-line options:
+
+* -d -- run in debug mode
+* -p [port] -- which port to listen on
+* -o [addr] -- what IP/host to listen on
+* -e [env] -- what 'environment' to use -- this isn't really used by
+  Gopher2000, but you could use it when writing your app to determine
+  how you behave in production vs development, etc.
+
+Command line options will override defaults specified in your script
+-- so you can try out things on a different port/address if needed.
+
+
+Developing Gopher Sites
+-----------------------
+
+Gopher2000 makes developing sites easy! Any time you change your
+script, Gopher2000 will reload it. This way, you can make tweaks and
+your site will be refreshed immediately. NOTE -- this is an
+experimental feature, and might need some work.
+
+Serving Files and Directories
+-----------------------------
+
+If you just want to serve up some files, there's a command for that:
+
+```rb
+mount '/files' => '/home/username/files', :filter => '*.jpg'
+```
+
+This will display a list of all the JPGs in the files directory.
+
+Outputting Gopher Menus
+-----------------------
+
+There are a collection of commands to output Gopher menus (see
+rendering/menu.rb for the code). The commands are:
+
+**line(type, text, selector)** - output a line of type 'type' -- see
+  the RFC for the different types of links you can have.
+
+**text** - output a line of text with no action on it.
+
+**br(x)** - output x blank lines.
+
+**error** - output an error message.
+
+**directory** - (aliased as menu) output a link to a 'directory' -- this could be an
+  actual directory if you're building some sort of filesystem tree, or
+  a sub-menu for other actions in your app.
+
+**link(text, selector)** - output a menu link to to the /selector path.
+
+**search(text, selector)** -- output a link to a search action at
+  /selector.
+
+Outputting Text
+---------------
+
+If you would like to output text, but have the ability to format it
+nicely, you can use a 'text' block like this:
+
+```rb
+route '/prettytext' do
+  render :prettytext
+end
+
+#
+# special text output rendering
+#
+text :prettytext do
+  @text = "A really long chunk of text. Lorem ipsum dolor sit amet ... nec massa."
+
+  # nicely wrapped text
+  block @text
+
+  # spacing
+  br(2)
+
+  # smaller line-width
+  block @text, 30
+end
+
+```
+
+A call to:
+
+```
+echo "/prettytext" | ncat -C localhost 7070
+```
+
+Will return your text, but with nice wrapping, etc.
+
+@todo headers, etc.
+
+
+Making It Pretty
+----------------
+
+There are several helpers which you can call within render blocks to
+help make your output a little shinier:
+
+**width(x)** will set the width of your output. The default is 80
+  characters. You can change this to make your output wider or
+  thinner. This setting is used by **block** and also by the methods
+  described below.
+
+**header(text, style='=')** will generate a very simple 'header', which is
+  basically the text you specify with an underline of the character
+  you specify. It will be centered in your output width, and will look
+  something like this:
+
+	     Hello There!
+	 =====================
+
+**big_header** is the same as header, except it is bigger and better!
+
+	 =====================
+	 =   Hello There!    =
+	 =====================
+
+**underline** can be used to just output plain old lines, if you're
+  into that sort of thing.
+
+
+Testing
+-------
+
+Here's some simple ways to test your server. First, you can always
+just install a
+[gopher client](http://lmgtfy.com/?q=gopher+clients). Or, if you like
+to live on the edge, there's a few commands worth learning. First, you
+can use [netcat](http://netcat.sourceforge.net/) to achieve
+awesomeness. Here's some examples, assuming you're running the example
+script on port 7070:
+
+
+```
+#
+# getting a menu listing
+#
+
+~/Projects/gopher2000: echo "/" | nc localhost 7070
+isimple gopher example	null	(FALSE)	0
+i	null	(FALSE)	0
+i	null	(FALSE)	0
+0current time	/time	0.0.0.0	7070
+i	null	(FALSE)	0
+0about	/about	0.0.0.0	7070
+i	null	(FALSE)	0
+7Hey, what is your name?	/hello	0.0.0.0	7070
+i	null	(FALSE)	0
+7echo test	/echo_test	0.0.0.0	7070
+i	null	(FALSE)	0
+1filez	/files	0.0.0.0	7070
+
+#
+# getting a simple text response
+#
+~/Projects/gopher2000: echo "/about" | nc localhost 7070
+Gopher 2000 -- World Domination via Text Protocols
+.
+```
+
+
+Or, you can use the equally awesome [ncat](http://nmap.org/ncat/),
+which is basically the successor to netcat. In general, I find that
+ncat works better, particularly if you're using non-blocking
+operations. Here's an example of it in operation:
+
+
+```
+#
+# Testing text output
+#
+
+~/Projects/gopher2000: echo "/about" | ncat -C localhost 7070
+Gopher 2000 -- World Domination via Text Protocols
+.
+
+#
+# testing a route with some input
+#
+
+~/Projects/gopher2000: echo "/hello\tcolin" | ncat -C localhost 7070
+iHello, colin!	null	(FALSE)	0
+
+.
+
+```
+
+
+
+Logging
+-------
+
+Logging is pretty basic at the moment. Right now debug messages are
+dumped to stderr. There's also an apache-esque access log, which can
+be written to a file specified like this:
+
+```rb
+set :access_log, "/tmp/access.log"
+```
+
+The log will rollover daily, so your million hits per day won't
+accumulate into an unmanageable file.
+
+The format is a pretty basic tab-delimited file:
+
+	timestamp 		   	ip_address	request_url		result_code	response_size
+	2012-04-05 19:14:01	127.0.0.1	/lookup			success		46
+
+Non-Blocking Requests
+---------------------
+
+When not running in debug mode, Gopher2000 will handle requests
+without blocking -- this way, if you have an app that handles slow
+requests, your users aren't held up waiting for other requests to
+finish. However, this is somewhat experimental, so you can turn it off
+by setting :non_blocking to be false in your script:
+
+```rb
+set :non_blocking, false
+```
+
+Also, non-blocking is always off in debug mode.
+
+You probably need to be wary of this feature if you're actually
+running a Gopher server that needs to be non-blocking. Read up on
+EventMachine's defer feature if you need to learn more.
+
+
+TODO
+----
+* More examples
+* Work on putting routing/rendering/etc into same context, and making
+  instance variables/methods generally available.
+* Documentation
+* clean up/improve EventMachine usage
+* stats generation
+
+References
+----------
+
+* http://www.ietf.org/rfc/rfc1436.txt -- the original RFC for the
+  Gopher Protocol
+* https://github.com/sinatra/sinatra -- almost everything good in this
+  library was taken or influenced by something in Sinatra. RUN don't
+  walk to the code and take a look.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'bundler'
+Bundler.setup :default, :test, :development
+
+require "bundler/gem_tasks"
+require 'rdoc/task'
+
+require "gopher2000/version"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov_opts = %w{--exclude .bundler,.rvm}
+  spec.rcov = true
+end
+
+task :default => :spec
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'yard'
+  YARD_OPTS = ['-m', 'markdown', '-M', 'redcarpet']
+  DOC_FILES = ['lib/**/*.rb', 'README.markdown']
+
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = DOC_FILES
+    #t.options = YARD_OPTS
+
+    puts t.inspect
+  end
+rescue LoadError
+  puts "You need to install YARD."
+end

data/bin/gopher2000

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+#
+# get rid of errors when running via bundle
+# @see https://github.com/ddollar/foreman/issues/94
+#
+$stdout.sync = true
+
+require 'optparse'
+require 'gopher2000'
+
+#
+# pull in any arguments and set them as env variables
+#
+opts = OptionParser.new
+opts.banner = <<-EOS
+
+Run a gopher server!
+
+Usage: #{File.basename($0)} [options] [scriptname]
+
+EOS
+
+opts.separator ""
+opts.separator "Options:"
+
+params = {
+  :debug => false,
+  :env => :production
+}
+
+opts.on('-d', '--debug', "run in debug mode")    { params[:debug] = true }
+opts.on('-p port',   'set the port (default is 70)')                { |val| params[:port] = Integer(val) }
+opts.on('-o addr',   'set the host (default is 0.0.0.0)')             { |val| params[host] = val }
+opts.on('-e env',    'set the environment (default is development)')  { |val| params[:env] = val.to_sym }
+
+opts.on_tail("-h", "--help", "Show this message") do
+  puts opts
+  exit!
+end
+
+extra = opts.parse!(ARGV)
+
+script = extra.shift
+
+if script.nil?
+  puts "Sorry, you need to specify a script to run"
+  exit!
+end
+
+run script, params

data/examples/default_route.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+
+#
+# Simple gopher example
+#
+
+require 'gopher2000'
+
+set :host, '0.0.0.0'
+set :port, 7070
+
+# you can specify a destination for access log, for stats/etc
+set :access_log, "/tmp/access.log"
+
+route '/gopher' do
+  "Greetings from Gopher 2000!" # You can output any text you want here
+end
+
+default_route do
+  "I AM HERE"
+end

data/examples/nyan.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+
+#
+# NYAN cat in gopherspace
+#
+
+require 'gopher2000'
+
+set :host, '0.0.0.0'
+set :port, 7070
+
+route '/nyan' do
+
+@cats = [
+" +      o     +              o
+     +             o     +       +
+ o          +
+     o  +           +        +
+ +        o     o       +        o
+ -_-_-_-_-_-_-_,------,      o
+ _-_-_-_-_-_-_-|   /\\_/\\
+ -_-_-_-_-_-_-~|__( ^ .^)  +     +
+ _-_-_-_-_-_-_-\"\"  \"\"
+ +      o         o   +       o
+     +         +
+ o        o         o      o     +
+     o           +
+ +      +     o        o      +   ",
+
+"     o  +           +        +
+ o          +                    o
+     o                 +
+ +      o     +              o
+  o     +        o               +
+ _-_-_-_-_-_-_-,------,  o      +
+ -_-_-_-_-_-_-_|   /\\_/\\    +
+ _-_-_-_-_-_-_~|__( ^ .^)     o
+ -_-_-_-_-_-_-_  \"\"  \"\"
+ +      +     o        o      +
+ o        +                o     +
+ +      o         +     +       o
+     +         +
+        +           o        +    ",
+
+  "░░▓▓░░░░░░░░▓▓░░
+░▓▒▒▓░░░░░░▓▒▒▓░
+░▓▒▒▒▓░░░░▓▒▒▒▓░
+░▓▒▒▒▒▓▓▓▓▒▒▒▒▓░
+░▓▒▒▒▒▒▒▒▒▒▒▒▒▒▓
+▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓
+▓▒▒▒░▓▒▒▒▒▒░▓▒▒▓
+▓▒▒▒▓▓▒▒▒▓▒▓▓▒▒▓
+▓▒░░▒▒▒▒▒▒▒▒▒░░▓
+▓▒░░▒▓▒▒▓▒▒▓▒░░▓
+░▓▒▒▒▓▓▓▓▓▓▓▒▒▓░
+░░▓▒▒▒▒▒▒▒▒▒▒▓░░
+░░░▓▓▓▓▓▓▓▓▓▓░░░"
+]
+
+  @cats.sample
+end