├── .gitignore ├── Gemfile ├── Rakefile ├── lispy.gemspec ├── lib └── lispy.rb ├── MIT-LICENSE ├── test └── lispy_test.rb └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | pkg/* 2 | *.gem 3 | .bundle 4 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "http://rubygems.org" 2 | 3 | # Specify your gem's dependencies in lispy.gemspec 4 | gemspec 5 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | require 'bundler' 2 | Bundler::GemHelper.install_tasks 3 | 4 | task :default do 5 | Rake::Task['run_tests'].invoke 6 | end 7 | 8 | task :run_tests do 9 | if RUBY_VERSION =~ /^1.9/ 10 | require_relative 'test/lispy_test' # for fuck's sake. 11 | else 12 | require 'test/lispy_test' 13 | end 14 | end 15 | -------------------------------------------------------------------------------- /lispy.gemspec: -------------------------------------------------------------------------------- 1 | # -*- encoding: utf-8 -*- 2 | $:.push File.expand_path("../lib", __FILE__) 3 | require "lispy" 4 | 5 | Gem::Specification.new do |s| 6 | s.name = "lispy" 7 | s.version = Lispy::VERSION 8 | s.platform = Gem::Platform::RUBY 9 | s.authors = ["Ryan Allen"] 10 | s.email = ["ryan@ryanface.com"] 11 | s.homepage = "http://rubygems.org/gems/lispy" 12 | s.summary = %q{Code as data in Ruby, without the metaprogramming madness.} 13 | s.description = %q{Create data structures in Ruby using idomatic 'DSL' constructs. Free yourself of metaprogramming madness, write nice APIs and decouple the implementation from it!} 14 | 15 | s.rubyforge_project = "lispy" 16 | 17 | s.files = `git ls-files`.split("\n") 18 | s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n") 19 | s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) } 20 | s.require_paths = ["lib"] 21 | end 22 | -------------------------------------------------------------------------------- /lib/lispy.rb: -------------------------------------------------------------------------------- 1 | class Lispy 2 | VERSION = '0.0.5' 3 | 4 | @@methods_to_keep = /^__/, /class/, /instance_/, /method_missing/, /object_id/ 5 | 6 | instance_methods.each do |m| 7 | undef_method m unless @@methods_to_keep.find { |r| r.match m } 8 | end 9 | 10 | def method_missing(sym, *args, &block) 11 | args = (args.length == 1 ? args.first : args) 12 | @scope.last << [sym, args] 13 | if block 14 | # there is some simpler recursive way of doing this, will fix it shortly 15 | if @remember_blocks_starting_with.include? sym 16 | @scope.last.last << block 17 | else 18 | @scope.last.last << [] 19 | @scope.push(@scope.last.last.last) 20 | instance_exec(&block) 21 | @scope.pop 22 | end 23 | end 24 | end 25 | 26 | def to_data(opts = {}, &block) 27 | @remember_blocks_starting_with = Array(opts[:retain_blocks_for]) 28 | _(&block) 29 | @output 30 | end 31 | 32 | private 33 | 34 | def _(&block) 35 | @output = [] 36 | @scope = [@output] 37 | instance_exec(&block) 38 | @output 39 | end 40 | end 41 | -------------------------------------------------------------------------------- /MIT-LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2011 Ryan Allen, Envato Pty Ltd 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /test/lispy_test.rb: -------------------------------------------------------------------------------- 1 | require 'test/unit' 2 | require 'lispy' 3 | 4 | class LispyTest < Test::Unit::TestCase 5 | def test_lispy 6 | output = Lispy.new.to_data do 7 | setup :workers => 30, :connections => 1024 8 | http :access_log => :off do 9 | server :listen => 80 do 10 | location '/' do 11 | doc_root '/var/www/website' 12 | end 13 | location '~ .php$' do 14 | fcgi :port => 8877 15 | script_root '/var/www/website' 16 | end 17 | end 18 | end 19 | end 20 | 21 | 22 | expected = [[:setup, {:workers=>30, :connections=>1024}], 23 | [:http, 24 | {:access_log=>:off}, 25 | [[:server, 26 | {:listen=>80}, 27 | [[:location, "/", [[:doc_root, "/var/www/website"]]], 28 | [:location, 29 | "~ .php$", 30 | [[:fcgi, {:port=>8877}], [:script_root, "/var/www/website"]]]]]]]] 31 | 32 | assert_equal expected, output 33 | end 34 | 35 | def test_moar_lispy 36 | output = Lispy.new.to_data do 37 | setup 38 | setup do 39 | lol 40 | lol do 41 | hi 42 | hi 43 | end 44 | end 45 | end 46 | 47 | expected = [[:setup, []], [:setup, [], [[:lol, []], [:lol, [], [[:hi, []], [:hi, []]]]]]] 48 | 49 | assert_equal expected, output 50 | end 51 | 52 | def lispy_but_conditionally_preserving_procs 53 | Lispy.new.to_data(:retain_blocks_for => [:Given, :When, :Then]) do 54 | Scenario "My first awesome scenario" do 55 | Given "teh shiznit" do 56 | #shiznit 57 | end 58 | 59 | When "I do something" do 60 | #komg.do_something 61 | end 62 | 63 | Then "this is pending" 64 | end 65 | end 66 | end 67 | 68 | def test_conditionally_preserving_procs 69 | quasi_sexp = lispy_but_conditionally_preserving_procs 70 | assert_equal :Scenario, quasi_sexp[0][0] 71 | assert_equal "My first awesome scenario", quasi_sexp[0][1] 72 | assert_equal :Given, quasi_sexp[0][2][0][0] 73 | assert_instance_of Proc, quasi_sexp[0][2][0].last 74 | end 75 | end 76 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # LISPY 2 | 3 | Yeah, right. Get a room, you two. 4 | 5 | ![Nothing to do with LISP, Problem?](http://1.bp.blogspot.com/_Tbc9D_HLbrs/TR3Vi-dyOnI/AAAAAAAAAOE/n8zDvBlzH3I/s320/troll-face_design.png) 6 | 7 | ## The backstory. 8 | 9 | I've written a number of Ruby libraries in my time. I've used many, many more. Wait, let's back up a bit. 10 | 11 | ## Assumptions. 12 | 13 | * People love libraries like Sinatra and ActiveRecord and Babushka and AASM and (name your favourite Ruby library). 14 | * What they love about these is the small amount of Ruby syntax required to get a whole lot done. 15 | * They love that they can contextualise their definitions (that make the libraries do things) with natural Ruby syntax such as blocks. 16 | * To enable these kinds of libraries the use of so-called 'meta-programming' constructs are required (instance_eval, instance_exec). 17 | * Clever but inexperienced Ruby programmers often make very useful libraries with wonderful APIs but horrible internals (my hand is up, see: Workflow). 18 | 19 | ## Goals. 20 | 21 | * Decouple the 'pretty Ruby junk' from the (hopefully) clean and explicit implementation that makes the library do it's job. 22 | * Allow library authors to dream up APIs and implement them without entering Ruby metaprogramming hell (it is a real place). 23 | 24 | ## Examples. 25 | 26 | Take the following example: 27 | 28 | Lispy.new.to_data do 29 | fart 1 30 | fart 2 31 | fart 3, 4 32 | fart 33 | fart :where => :in_bed 34 | end 35 | 36 | This will return `[[:fart, 1], [:fart, 2], [:fart, [3, 4]], [:fart, []], [:fart, {:where => :in_bed}]]`. It looks somewhat like an abstract syntax tree (I think). Let's take an example with nesting: 37 | 38 | Lispy.new.to_data do 39 | todo_list do 40 | item :priority => :high do 41 | desc 'Take out the trash, it stinks.' 42 | end 43 | item :priority => :normal do 44 | desc 'Walk the dog.' 45 | end 46 | item :priority => :normal do 47 | desc 'Feed the cat.' 48 | end 49 | end 50 | interested_parties do 51 | person 'Me.' 52 | person 'You.' 53 | person '...' 54 | end 55 | end 56 | 57 | The pretty printed output is this, but before you continue, I ask you to take a deep breath, and remember that you are a programmer and that you have been writing Ruby for too long to be able to look at anything else than ActiveRecord declarations and say something along the lines of "WTF IS THIS, IT IS BAD CODE OMFG I AM TELLING!!!1". Yes, once upon a time you were able to think as a programmer and once you had patience! Now, that output: 58 | 59 | [[:todo_list, []], 60 | [[:item, {:priority=>:high}], 61 | [[:desc, "Take out the trash, it stinks."]], 62 | [:item, {:priority=>:normal}], 63 | [[:desc, "Walk the dog."]], 64 | [:item, {:priority=>:normal}], 65 | [[:desc, "Feed the cat."]]], 66 | [:interested_parties, []], 67 | [[:person, "Me."], [:person, "You."], [:person, "..."]]] 68 | 69 | That last example, I just wrote off the top of my head. You see how you can start with an API design and worry about implementation later? If you haven't tried to make a 'nice' Ruby library before, this wont be self evident, but for those that have, and have struggled through all the madness, you'll see what I mean. Once you've made up your API, all you have to do is write the translation library that does whatever that needs to be done. If that is piping out to a shell, writing a configuration file or constructing an object graph, then well, you're covered aren't you? 70 | 71 | Your crazy so-called 'DSL' is now decoupled from your wonderfully explicitly programmed library, I hope. Because I might have to modify it one day and man, if I see a rats nest of instance_execs and auto-generated classes I might just... write you a nasty letter. With angry faces like this: >:| 72 | 73 | ## Now what? 74 | 75 | If you have any questions about this, or how I'm using it for real-world problems (I am!), please get in touch. Pete won't talk to me about this, and I bought his car and everything!!! 76 | 77 | ## Why Lispy? 78 | 79 | To my mind, this whole API fandangle we've gotten ourselves into is due to Ruby having a nice enough syntax to describe APIs in a way that is easy to understand, but Ruby itself wasn't designed with this usage in mind. When I see lines like `has_one :brain` and `dep 'nginx' do` it reminds me of a feature of LISP, which is code as data. Ruby doesn't have this code as data facility but I reckon if it did, we'd have cleaner library implementations with it's idomatic syntax. 80 | 81 | Saying that, I've written about 10 lines of LISP in my life. Pete keeps telling me to go read SICP and I keep meaning to but then I end up at the local bar listening to some rock band and I'm like "crap, it's 3am". And even then, I wont get to use LISP at work because I don't think anyone in our company except for Pete has actually read SICP. 82 | 83 | ## License. 84 | 85 | Released under the MIT license (see MIT-LICENSE). GPL can go fart itself, seriously. I like open source, but I also like money. 86 | --------------------------------------------------------------------------------