Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

first stab at documentation

  • Loading branch information...
commit 1f62e56f545ed8c51560ff142ed9d41819fa3c63 1 parent f45c3cf
Marc Siegel authored
View
7 .yardopts
@@ -0,0 +1,7 @@
+--title 'Docile Documentation'
+
+--no-private
+--hide-void-return
+
+--markup-provider=redcarpet
+--markup=markdown
View
19 LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2011 Marc Siegel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
View
0  LICENSE.txt
No changes.
View
75 README.md
@@ -0,0 +1,75 @@
+# Docile
+
+Definition: *Ready to accept control or instruction; submissive* [[1]]
+
+Tired of overly complex DSL libraries and hairy meta-programming?
+Let's make our Ruby DSLs more *docile*...
+
+[1]: http://www.google.com/search?q=docile+definition "Google"
+
+## Usage
+
+Let's treat an Array's methods as its own DSL:
+
+``` ruby
+Docile.dsl_eval [] do
+ push 1
+ push 2
+end
+#=> [1, 3]
+```
+
+Mutating (changing) the array is fine, but what you probably really want as your DSL is actually a [Builder Pattern][2].
+
+For example, if you have a PizzaBuilder class that can build a pizza:
+
+``` ruby
+@sauce_level = :extra
+pizza = PizzaBuilder.new.cheese.pepperoni.bacon.sauce(@sauce_level).build
+```
+
+Then you can use this PizzaBuilder class as a DSL:
+
+``` ruby
+@sauce_level = :extra
+pizza = Docile.dsl_eval PizzaBuilder.new do
+ cheese
+ pepperoni
+ bacon
+ sauce @sauce_level
+end.build
+```
+
+[2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern "Builder Pattern"
+
+## Features
+
+ 1. method lookup falls back from the DSL object to the block's context
+ 2. local variable lookup falls back from the DSL object to the block's context
+ 3. instance variables are from the block's context only
+
+## Installation
+
+``` bash
+$ gem install docile
+```
+
+## Documentation
+
+Documentation hosted on *rubydoc.info*: [Docile Documentation](http://rubydoc.info/gems/docile)
+Or, read the code hosted on *github.com*: [Docile Code](https://github.com/ms-ati/docile)
+
+## Note on Patches/Pull Requests
+
+ * Fork the project.
+ * Setup your development environment with: gem install bundler; bundle install
+ * Make your feature addition or bug fix.
+ * Add tests for it. This is important so I don't break it in a
+ future version unintentionally.
+ * Commit, do not mess with rakefile, version, or history.
+ (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+ * Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2011 Marc Siegel. See LICENSE for details.
View
6 Rakefile
@@ -1,9 +1,11 @@
require "bundler/gem_tasks"
+require "github/markup"
+require "redcarpet"
require "yard"
require "yard/rake/yardoc_task"
YARD::Rake::YardocTask.new do |t|
- OTHER_PATHS = %w(README.md LICENSE)
+ OTHER_PATHS = %w()
t.files = ['lib/**/*.rb', OTHER_PATHS]
- t.options = ['--main', 'README.md']
+ t.options = %w(--markup-provider=redcarpet --markup=markdown)
end
View
8 docile.gemspec
@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
s.authors = ["Marc Siegel"]
s.email = ["msiegel@usainnov.com"]
s.homepage = "http://docile.github.com"
- s.summary = "Docile helps keep your DSLs tame and well-behaved'"
- s.description = "Docile handles ruby DSL evaluation best-practices so you can concentrate on your project"
+ s.summary = "Docile keeps your Ruby DSL's tame and well-behaved"
+ s.description = "Docile turns any Ruby object into a DSL. Especially useful with the Builder pattern."
s.rubyforge_project = "docile"
@@ -19,6 +19,10 @@ Gem::Specification.new do |s|
s.require_paths = ["lib"]
s.add_development_dependency "rspec", "~> 2.7.0"
+
+ # Github flavored markdown in YARD documentation
+ # http://blog.nikosd.com/2011/11/github-flavored-markdown-in-yard.html
s.add_development_dependency "yard"
s.add_development_dependency "redcarpet"
+ s.add_development_dependency "github-markup"
end
View
2  lib/docile/version.rb
@@ -1,3 +1,3 @@
module Docile
- VERSION = "0.1.0"
+ VERSION = "0.9.0"
end
Please sign in to comment.
Something went wrong with that request. Please try again.