brief 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5de4de1da31d941ba973047d92612413463c2cfa
-  data.tar.gz: 9fbd98bbe85b00b6fdefabde34f79c03e6ceb6d4
+  metadata.gz: 4ea25b279da5166d726a9463be10836ab9b6d7bb
+  data.tar.gz: e52d0270a01c924196c8ab59250df0973320589d
 SHA512:
-  metadata.gz: 47d96dd1a4537378b35dc5af7f8fef84e0d80fc484497d14c90119fed09776f3274ac0b464402f858f7348f555a26e8cb45dcb9d488124ad56010ef950661d3b
-  data.tar.gz: 536970830fd8c5d7b4c4b1a3eaad68043932f5b562d07d5b714f3852db1c39eb5ba3847c4f62d056e17ab291d772d10d4f0fb1a3d3cb656d255233c540b23525
+  metadata.gz: 250b23f611f467ec9731114557f84d8bf24e498642849eab59dcb79f7a7c1790ea33b8f734a3017f515ad025caf5353625b0ec972c7e016eb7682eafe9aa063a
+  data.tar.gz: 88a4250edb54523fdb51f18700a149831a5835d031cf67fbc49c142bb6d3abeccec9eff48c32df99f9ded979330c9223b7f7934819b87e4f79f33a67292b2e3e

data/.gitignore

@@ -0,0 +1,2 @@
+# the test suite writes to this
+spec/fixtures/example/docs/epic.html.md

data/README.md

@@ -2,171 +2,110 @@
 
 An ActiveRecord style layer on top of a folder of markdown files.
 
-### No more dead documents 
+Treat your markdown documents as active models, run actions on them,
+convert them into HTML, extract fragments of HTML, combine it all in
+whatever interesting way you can think of.  
 
-Brief is a tool that lets you build simple applications on top of
-collections of markdown files.  The metaphor we use is a briefcase,
-which contains folders with different document types.
+The end result is a really neat way of being able to use the words that you write
+to power all sorts of applications. 
 
-Every document type, or model, can define a simple schema of attributes, 
-which can be specified in a YAML frontmatter preamble at the very top of
-each document.  
+**No more writing dead documents!**
 
-In addition to frontmatter metadata, you can declare other model
-attributes as CSS selectors.  For example, the very first h1 heading
-could be the title for your document, and the corresponding model for
-that document would have a `title` method which returned its value.
+### Documents as Models
 
-This is a great way to build applications whose primary interface is the
-text editor, allowing writing and thought to flow as freely as possible
-and to later be used to power some automation tasks.
-
-**Think of it as an ActiveRecord like layer on top of a folder of
-Markdown files**.  Brief turns static text into a 'living' data object.
-
-## Getting started 
-
-```bash
-gem install brief
-mkdir blog
-cd blog 
-brief init
-```
-
-This will create a new folder for your briefcase, along with the
-following config file and structure.
-
-```
-- docs/
-  - an-introduction-to-brief.html.md
-- models/
-- brief.rb
-```
-
-The config file will look like:
+Brief lets you treat an individual markdown file as if it were a model,
+complete with validations, callbacks, and methods you can run. You can
+define a `Post` model for all of the files in a 'posts' folder and
+define actions like 'publish' on them. 
 
 ```ruby
-
-# configuration options for this briefcase
-config do
-  set(:models_path => Pathname(__FILE__).parent.join("models"))
-end
-
-# define a Post model
-define("Post") do
-
-  # the post model will have YAML frontmatter 
-  # with values for 'status' and 'date'
+define "Post" do
   meta do
     status
-    date DateTime, :default => lambda {|post, attr| post.document.created_at }
+    tags Array
   end
-  
-  # the post model will have a 'title' method which returns the text
-  # from the first h1 heading
+
   content do
-    title "h1"
+    has_one :title, "h1"
     has_many :subheadings, "h2"
   end
 
-  helpers do
-    def publish(options={})
-
+  actions do
+    def publish
+      update_attributes(:status => "published")
     end
   end
-  
-  # Whenever we call post.save() and the status attribute changes
-  # from draft to published, do something with the model
-  on_status_change(:from => "draft", :to => "published") do |model|
-    # Do Something
-    # mail_service.send_html_email_campaign(model.to_html)
-  end
 end
+```
 
-# this creates a custom command in the brief CLI tool
-#
-# so when you run:
-# 
-#   brief publish posts /path/to/*.html.md.
-#
-# the brief CLI will find models for the post files you reference,
-# and call whatever methods you want.
 
-action "publish posts" do |briefcase, models, options|
+### Model attributes derived from YAML frontmatter 
 
-  say "== Publishing #{ models.length } posts"
+Models can get their attributes from headers on the document, aka YAML frontmatter.
 
-  Array(models).each do |post|
-    post.publish()
-  end
-end
+```markdown
+---
+status: draft
+tags: 
+  - demo
+  - sample
+---
+
+# Title
+
+## Section One
+## Section Two
 ```
 
-### Real World Application
+which will let you use it like such:
+
+```ruby
+post = Brief::Document.new(/path/to/doc.html.md)
+
+post.status #=> "draft"
+post.title #=> "Title"
+post.tags #=> ['demo','sample']
+```
 
-My company Architects.io, Inc. uses brief to power our Blueprint
-software.  A Blueprint is a collection of related documents that are
-used in the software architecture and design process, as well as in the
-day to day writing that takes place while building the software itself.
+#### Model attributes derived from the document structure
 
-This includes things like:
+Models can also get their attributes from the structure itself.
 
-- daily standups
-- bug reports
-- code reviews
-- feature epics
-- user stories
-- integration tests
-- release notes
-- wireframe annotations
+```ruby
+post.title #=> "Title"
+post.subheadings #=> ["Section One", "Section Two"]
+```
 
-All of these things are simple markdown files.  They live in the
-projects we are working on, and by treating our writing as a structured
-exercise we are able to do a lot more things with it than just read it.
+### Querying Documents
 
-For example we can do:
+Given a big folder of markdown files with attributes, we can query them:
 
 ```
-brief publish user stories /path/to/user-stories/*.html.md
+posts = briefcase.posts.where(:status => "published")
+posts.map(&:title) #=> ['Title']
 ```
 
-which is implemented by:
+This functionality is based on https://github.com/ralph/document_mapper,
+and similar to middleman.
 
-```ruby
-# brief.rb
+### Document Actions
 
-define "User Story" do
-  meta do
-    status
-  end
+By defining actions on documents like so:
 
-  content do
-    title "h1"
-    paragraph "p:first-child"
-    persona "p:first-child strong:1st-child"
-    behavior "p:first-child strong:2nd-child"
-    goal "p:first-child strong:3rd-child"
-  end
+```ruby
 
-  helpers do
-    def create_github_issue
-      issue = github.create_issue(title: title, body: document.content)
-      set(issue_number: issue.number)
+define "Post" do
+  actions do
+    def publish
+      # DO Something
     end
   end
 end
+```
 
-action "publish user stories" do |briefcase, models, options|
-  user_stories = models
+you can either call that method as you normally would, or you can run 
+that action from the command line:
 
-  user_stories.each do |user_story|
-    if user_story.create_github_issue()
-      user_story.status = "published"
-      user_story.save
-    end
-  end
-end
+```bash
+brief publish posts ./posts/*.html.md
 ```
-
-As you can see, Brief can be a way to make your Markdown writing efforts
-much more productive. 

data/TUTORIAL.md

@@ -0,0 +1,146 @@
+## Tutorial
+
+```bash
+gem install brief
+mkdir blog
+cd blog 
+brief init
+```
+
+This will create a new folder for your briefcase, along with the
+following config file and structure.
+
+```
+- docs/
+  - an-introduction-to-brief.html.md
+- models/
+- brief.rb
+```
+
+The config file will look like:
+
+```ruby
+
+# configuration options for this briefcase
+config do
+  set(:models_path => Pathname(__FILE__).parent.join("models"))
+end
+
+# define a Post model
+define("Post") do
+
+  # the post model will have YAML frontmatter 
+  # with values for 'status' and 'date'
+  meta do
+    status
+    date DateTime, :default => lambda {|post, attr| post.document.created_at }
+  end
+  
+  # the post model will have a 'title' method which returns the text
+  # from the first h1 heading
+  content do
+    title "h1"
+    has_many :subheadings, "h2"
+  end
+
+  helpers do
+    def publish(options={})
+
+    end
+  end
+  
+  # Whenever we call post.save() and the status attribute changes
+  # from draft to published, do something with the model
+  on_status_change(:from => "draft", :to => "published") do |model|
+    # Do Something
+    # mail_service.send_html_email_campaign(model.to_html)
+  end
+end
+
+# this creates a custom command in the brief CLI tool
+#
+# so when you run:
+# 
+#   brief publish posts /path/to/*.html.md.
+#
+# the brief CLI will find models for the post files you reference,
+# and call whatever methods you want.
+
+action "publish posts" do |briefcase, models, options|
+
+  say "== Publishing #{ models.length } posts"
+
+  Array(models).each do |post|
+    post.publish()
+  end
+end
+```
+
+### Real World Application
+
+My company Architects.io, Inc. uses brief to power our Blueprint
+software.  A Blueprint is a collection of related documents that are
+used in the software architecture and design process, as well as in the
+day to day writing that takes place while building the software itself.
+
+This includes things like:
+
+- daily standups
+- bug reports
+- code reviews
+- feature epics
+- user stories
+- integration tests
+- release notes
+- wireframe annotations
+
+All of these things are simple markdown files.  They live in the
+projects we are working on, and by treating our writing as a structured
+exercise we are able to do a lot more things with it than just read it.
+
+For example we can do:
+
+```
+brief publish user stories /path/to/user-stories/*.html.md
+```
+
+which is implemented by:
+
+```ruby
+# brief.rb
+
+define "User Story" do
+  meta do
+    status
+  end
+
+  content do
+    title "h1"
+    paragraph "p:first-child"
+    persona "p:first-child strong:1st-child"
+    behavior "p:first-child strong:2nd-child"
+    goal "p:first-child strong:3rd-child"
+  end
+
+  helpers do
+    def create_github_issue
+      issue = github.create_issue(title: title, body: document.content)
+      set(issue_number: issue.number)
+    end
+  end
+end
+
+action "publish user stories" do |briefcase, models, options|
+  user_stories = models
+
+  user_stories.each do |user_story|
+    if user_story.create_github_issue()
+      user_story.status = "published"
+      user_story.save
+    end
+  end
+end
+```
+
+As you can see, Brief can be a way to make your Markdown writing efforts
+much more productive. 

data/examples/blog/brief.rb

@@ -20,35 +20,9 @@ define("Post") do
     has_many :subheadings, "h2"
   end
 
-  helpers do
+  actions do
     def publish(options={})
-
+      puts "The publish action"
     end
   end
-
-  # Whenever we call post.save() and the status attribute changes
-  # from draft to published, do something with the model
-  on_status_change(:from => "draft", :to => "published") do |model|
-    # Do Something
-    # mail_service.send_html_email_campaign(model.to_html)
-  end
-end
-
-# this creates a custom command in the brief CLI tool
-#
-# so when you run:
-#
-#   brief publish posts /path/to/*.html.md.
-#
-# the brief CLI will find models for the post files you reference,
-# and call whatever methods you want.
-
-action "publish posts" do |briefcase, models, options|
-
-  say "== Publishing #{ models.length } posts"
-
-  Array(models).each do |post|
-    post.publish()
-  end
 end
-

data/lib/brief.rb

@@ -28,6 +28,13 @@ module Brief
 
   def self.load_commands
     Dir[gem_root.join("brief","cli","**/*.rb")].each {|f| require(f) }
+
+    # the instance methods which get defined with the helper
+    Brief::Model.classes.each do |klass|
+      Array(klass.defined_actions).uniq.each do |action|
+        Brief::Util.create_method_dispatcher_command_for(action, klass)
+      end
+    end
   end
 
   def self.load_models(from_folder=nil)
@@ -37,6 +44,7 @@ end
 
 require "brief/core_ext"
 require "brief/version"
+require "brief/util"
 require "brief/configuration"
 require "brief/document/rendering"
 require "brief/document/front_matter"

data/lib/brief/document_mapper.rb

@@ -1,3 +1,4 @@
+# Credit to github.com/ralph/document_mapper
 module Brief::DocumentMapper
   OPERATOR_MAPPING = {
     'equal'     => :==,

data/lib/brief/model.rb

@@ -13,9 +13,10 @@ module Brief
       include AccessorMethods
       include Persistence
 
-      class_attribute :models, :after_initialization_hooks, :defined_helpers
+      class_attribute :models, :after_initialization_hooks, :defined_actions
 
       self.models = Array(self.models).to_set
+      self.defined_actions = Array(self.defined_actions).to_set
 
       class << self
         include Enumerable
@@ -69,21 +70,7 @@ module Brief
 
     def self.finalize
       Virtus.finalize
-
-      classes.each do |klass|
-        klass.name ||= klass.to_s.split('::').last.humanize
-        klass.type_alias ||= klass.name.parameterize.gsub(/-/,'_')
-
-        klass.attribute_set.map(&:name).each do |attr|
-          klass.define_singleton_method("find_by_#{ attr }") do |value|
-            where(attr => value).first
-          end
-        end
-
-        klass.definition.apply_config
-      end
-
-      Brief::Repository.define_document_finder_methods
+      classes.each(&:finalize)
     end
 
     def ==(other)
@@ -95,24 +82,35 @@ module Brief
     end
 
     module ClassMethods
-      def where(*args, &block)
-        Brief::DocumentMapper::Query.new(self).send(:where, *args)
+      def has_actions?
+        definition.has_actions?
       end
 
-      def each(*args, &block)
-        Array(self.models).send(:each, *args, &block)
-      end
+      def finalize
+        klass = self
+
+        klass.name ||= klass.to_s.split('::').last.humanize
+        klass.type_alias ||= klass.name.parameterize.gsub(/-/,'_')
+
+        klass.attribute_set.map(&:name).each do |attr|
+          unless klass.method_defined?("find_by_#{ attr }")
+            klass.define_singleton_method("find_by_#{ attr }") do |value|
+              where(attr => value).first
+            end
+          end
+        end
+
+        klass.definition.apply_config
 
-      def meta(options={}, &block)
-        definition.send(:meta, options, &block)
+        Brief::Repository.define_document_finder_methods
       end
 
-      def content(options={}, &block)
-        definition.send(:content, options, &block)
+      def where(*args, &block)
+        Brief::DocumentMapper::Query.new(self).send(:where, *args)
       end
 
-      def actions(&block)
-        definition.send(:helpers, &block)
+      def each(*args, &block)
+        Array(self.models).send(:each, *args, &block)
       end
 
       def after_initialize(&block)
@@ -144,7 +142,10 @@ module Brief
       end
 
       def method_missing(meth, *args, &block)
-        if meth.to_s.match(/^on_(.*)_change$/)
+        if %w(meta content actions helpers).include?(meth.to_s)
+          definition.send(meth, &block)
+          finalize
+        elsif meth.to_s.match(/^on_(.*)_change$/)
           create_change_handler($1, *args, &block)
         else
           super

data/lib/brief/model/definition.rb

@@ -27,7 +27,7 @@ module Brief
         create_model_class.tap do |k|
           k.send(:include, Brief::Model)
 
-          k.definition = definition
+          k.definition ||= definition
 
           k.name ||= name
           k.type_alias ||= type_alias
@@ -40,21 +40,22 @@ module Brief
     end
 
     def apply_config
+      # define a virtus attribute mapping
       metadata_schema.values.each do |settings|
-        if model_class.nil?
-          binding.pry
-        end
-
         model_class.send(:attribute, *(settings[:args]))
       end
 
-      Array(self.defined_helpers).each do |mod|
-        model_class.send(:include, mod)
-      end
+      # defined helpers adds an anonymous module include
+      Array(self.defined_helpers).each {|mod| model_class.send(:include, mod) }
+
+      model_class.defined_actions += Array(self.defined_actions)
+      true
     end
 
     def create_model_class
-      model_namespace.const_set(type_alias.camelize, Class.new) unless model_class
+      unless (model_namespace.const_get(type_alias.camelize) rescue nil)
+        model_namespace.const_set(type_alias.camelize, Class.new)
+      end
     end
 
     def model_class
@@ -75,6 +76,18 @@ module Brief
       instance_eval(&block)
     end
 
+    def has_actions?
+      !@defined_actions.empty?
+    end
+
+    def actions(&block)
+      helpers(&block)
+    end
+
+    def defined_actions
+      Array(defined_helpers).map(&:instance_methods).flatten
+    end
+
     def helpers(&block)
       self.defined_helpers ||= []
 

data/lib/brief/model/persistence.rb

@@ -0,0 +1,7 @@
+module Brief
+  module Model::Persistence
+    extend ActiveSupport::Concern
+
+
+  end
+end

data/lib/brief/util.rb

@@ -0,0 +1,36 @@
+module Brief::Util
+  def self.create_method_dispatcher_command_for(action, klass)
+    identifier = "#{ action } #{ klass.type_alias.to_s.pluralize }"
+
+    Object.class.class_eval do
+      command "#{identifier}" do |c|
+        c.syntax = "brief #{identifier}"
+        c.description = "run the #{identifier} command"
+
+        c.action do |args, opts|
+          briefcase = Brief.case
+
+          path_args = args.select {|arg| arg.is_a?(String) && arg.match(/\.md$/) }
+
+          path_args.select! do |arg|
+            path = briefcase.repository.root.join(arg)
+            path.exist?
+          end
+
+          path_args.map! {|p| briefcase.repository.root.join(p) }
+
+          models = path_args.map {|path| Brief::Document.new(path) }.map(&:to_model)
+
+          if models.empty?
+            model_finder = c.name.to_s.split(' ').last
+            models = briefcase.send(model_finder)
+          end
+
+          models.each do |model|
+            model.send(action)
+          end
+        end
+      end rescue nil
+    end
+  end
+end

data/lib/brief/version.rb

@@ -1,3 +1,3 @@
 module Brief
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/fixtures/example/brief.rb

@@ -15,13 +15,13 @@ define "User Story" do
     goal "p strong:third-child"
   end
 
-  helpers do
+  actions do
     def defined_helper_method
       true
     end
-  end
-end
 
-action "custom command" do
-  $custom_command = true
+    def custom_action
+      true
+    end
+  end
 end

data/spec/fixtures/example/models/epic.rb

@@ -2,7 +2,8 @@ class Brief::Epic
   include Brief::Model
 
   meta do
-    title String
+    title
+    subheading
     status String, :in => %w(draft published)
   end
 
@@ -13,4 +14,9 @@ class Brief::Epic
       has_many :user_stories, "h2" => "title", "p:first-child" => "paragraph"
     end
   end
+
+  actions do
+    def custom_action
+    end
+  end
 end

data/spec/lib/brief/model_spec.rb

@@ -31,6 +31,11 @@ describe "The Brief Model" do
       set = Brief::Model::UserStory.attribute_set.map(&:name)
       expect(set).to include(:title, :status, :epic_title)
     end
+
+    it "has attribute setters" do
+      story = Brief::Model::UserStory.new
+      expect(story).to respond_to(:title=)
+    end
   end
 
   context "Class Definitions" do
@@ -55,6 +60,12 @@ describe "The Brief Model" do
       set = Brief::Epic.attribute_set.map(&:name)
       expect(set).to include(:path, :document, :title, :status)
     end
+
+    it "has attribute setters" do
+      epic = Brief::Epic.new
+      expect(epic).to respond_to(:title=)
+      expect(epic).to respond_to(:subheading=)
+    end
   end
 
   context "Briefcase Finders" do
@@ -81,4 +92,14 @@ describe "The Brief Model" do
       expect(epic.extracted.title).to eq("Blueprint Epic Example")
     end
   end
+
+  context "Actions and Helpers" do
+    it "uses the actions block to define CLI dispatchers" do
+      expect(epic.class.defined_actions).to include(:custom_action)
+    end
+
+    it "users the actions block to define CLI dispatchers (dsl)" do
+      expect(user_story.class.defined_actions).to include(:custom_action)
+    end
+  end
 end

data/spec/lib/brief/persistence_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+
+describe "Updating Model Data" do
+  let(:briefcase) { Brief.example }
+
+  it "lets me set new attributes on the model" do
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonathan Soeder
@@ -215,11 +215,13 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
+- TUTORIAL.md
 - bin/brief
 - brief.gemspec
 - examples/blog/brief.rb
@@ -229,7 +231,6 @@ files:
 - lib/brief/briefcase.rb
 - lib/brief/cli/change.rb
 - lib/brief/cli/init.rb
-- lib/brief/cli/publish.rb
 - lib/brief/cli/write.rb
 - lib/brief/configuration.rb
 - lib/brief/core_ext.rb
@@ -241,7 +242,9 @@ files:
 - lib/brief/dsl.rb
 - lib/brief/model.rb
 - lib/brief/model/definition.rb
+- lib/brief/model/persistence.rb
 - lib/brief/repository.rb
+- lib/brief/util.rb
 - lib/brief/version.rb
 - spec/fixtures/example/brief.rb
 - spec/fixtures/example/docs/concept.html.md
@@ -256,6 +259,7 @@ files:
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb
 - spec/lib/brief/model_spec.rb
+- spec/lib/brief/persistence_spec.rb
 - spec/lib/brief/repository_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_helpers.rb
@@ -298,6 +302,7 @@ test_files:
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb
 - spec/lib/brief/model_spec.rb
+- spec/lib/brief/persistence_spec.rb
 - spec/lib/brief/repository_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_helpers.rb