alki 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d65c6ea707a3c2b160cf29edcb6cdd092a9239f3
-  data.tar.gz: 9ec9b017122f9a6a0cd2c5741835e2a0b0bd570b
+  metadata.gz: c3e661fb5cb33a76f94430ca79d62dae03fb2527
+  data.tar.gz: 4c288022884681ff99906ac0787cc4c82bb25c1d
 SHA512:
-  metadata.gz: ad08a969ea2df6707a7e92139a52d70d1cbf5549d5bf5566dfe11f1253b5b014d2e4db986dd94585db0a85faf9a0aacc93cffcd04d7e01efe41695f940e47216
-  data.tar.gz: b0ba6db2280081859a064f287b144ec7425de30f0d090370c900c8b0e37c2b56562a4599e9be97f4b2ba6044f9a4fb7f9102db2cb6cb1bec7e1c266777b03f9c
+  metadata.gz: c3c44874d4ce17e340d25224b8c5131bc00d4f9595bd09bdf85f22aab2d296a493d1cee68e5f97ffa7794c2e8859bb6bb7cfb18e40c8af5727ecc6777982ba69
+  data.tar.gz: f86c11fed68fb98600efb661fb6c1c255212690e18f42bf7fa2bef59df220c5f469d9d2a461a94f7e59c765b0473e605ee7abcd95d6fbbe86758d9a399fdc239

data/Gemfile

@@ -1,5 +1,6 @@
 source 'https://rubygems.org'
 
 gem 'alki-testing'
+gem 'rake'
 
 gemspec

data/README.adoc

@@ -1,34 +1,146 @@
 # What is Alki?
 
-Alki is a small framework for Ruby that provides a powerful dependency injection and program
-management system with helpers for testing, creating executables, and writing DSLs.
+Alki is a small library to help organize and scale your Ruby project, so you can focus on the
+important stuff. It can be used alongside frameworks such as Ruby on Rails.
 
-It's goal is to remove uncertainty and friction when building Ruby projects, allowing developers to focus on
-implementing business logic. It can be used alongside other frameworks such as Ruby on Rails.
+Some high level features:
 
-Alki tries to combine time tested software engineering concepts such as
-https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)[SOLID],
-and  https://en.wikipedia.org/wiki/Inversion_of_control[Inversion of Control], with
-Ruby style ease of use, DSLs, and
-https://en.wikipedia.org/wiki/Convention_over_configuration[Convention over Configuration].
+* Easily manage objects and dependencies
+* Enables writing reusable and testable code
+* Developer console (built on pry)
+* Automatic code reloading on changes in development
+* Powerful DSL toolkit
+* Extensible
 
-Further documentation can be found at https://github.com/alki-project/alki/blob/master/doc/index.adoc
 
-Example projects can be found at https://github.com/alki-project/alki-examples
+## Installation
 
-## Getting Started
+Add this line to your application's Gemfile:
 
-Install from rubygems
+```ruby
+gem 'alki'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install alki
+
+## Introduction
+
+[NOTE]
+Full "todo" example can be found https://github.com/alki-project/alki-examples/tree/master/todo[here]
+
+Alki simplifies project organization by pulling out all of the "connective tissue"
+that connects our classes and modules together, and puts them into a special object
+called an Assembly.
+
+There are many ways to use Assemblies, but the most common is to have a single
+Assembly for you project. For example, if you hade a "todo" command line utility
+project that you wanted to use Alki with, all you would need to do to create
+an Assembly is add this file.
 
-    gem install alki
+.lib/todo.rb
+```ruby
+require 'alki'
+Alki.project_assembly!
+```
 
-Setting up Alki in your project requires only creating a couple of files, but the
-`alki` command line tool can also be used to automate the process. Project names
-should be given in lowercase using underscores and forward slashes as separators.
+This will create a module called `Todo` that is an empty assembly:
 
-.Example project
 ```
-$ cd <project dir>
-$ alki init --addons console <project name>
+$ bundle exec irb -Ilib
+2.4.0 :001 > require 'todo'
+ => true
+2.4.0 :002 > todo = Todo.new
+ => #<Todo:21964520>
+```
+
+### Defining Elements
+
+Add things to the assembly requires an assembly definition file. By convention this is
+named `config/assembly.rb` and is built using a simple DSL. There are
+a handful of different element types in Assemblies. Below are a few of the
+most common. Full documentation of the DSL can be found
+https://github.com/alki-project/alki/blob/master/doc/assembly_dsl.adoc[here]
+
+.config/assembly.rb
+```ruby
+Alki do
+  group :settings do <1>
+    set(:home) { ENV['HOME'] } <2>
+    set(:db_path) { ENV['TODO_DB_PATH'] || File.join(home,'.todo_db2') }
+    set :prompt, 'todo> '
+  end
+
+  service :interface do <3>
+    require 'todo/readline_interface'
+    Todo::ReadlineInterface.new settings.prompt, handler
+  end
+
+  service :handler do
+    require 'todo/command_handler'
+    Todo::CommandHandler.new db
+  end
+
+  service :db do
+    require 'todo/store_db'
+    Todo::StoreDb.new file_store
+  end
+
+  service :file_store do
+    require 'todo/json_file_store'
+    Todo::JsonFileStore.new settings.db_path
+  end
+end
 ```
+<1> `group` allows bundling together subelements and can be moved to their own files
+<2> `set` defines simple values
+<3> `service` defines our main application objects
+
+Any element can be accessed directly from the assembly object.
+
+```
+$ bundle exec irb -Ilib
+2.4.0 :001 > require 'todo'
+ => true
+2.4.0 :002 > todo = Todo.new
+ => #<Todo:21964520>
+2.4.0 :003 > todo.settings.prompt
+ => 'todo> '
+```
+
+The 'alki-console' tool can also be used to quickly work with assemblies.
+Add `gem 'alki-console'` to your Gemspec and run `bundle --binstubs`.
+
+```
+$ bin/alki-console
+todo> settings.prompt
+=> 'todo> '
+```
+
+### Creating an executable
+
+Read more about creating executables with Alki
+https://github.com/alki-project/alki/blob/master/doc/executables.adoc[here]
+
+In the todo example, it's a CLI utility so it requires an executable.
+
+.exe/todo
+```ruby
+require 'todo'
+Todo.new.interface.run
+```
+
+## Further Documentation
+
+Further documentation can be found https://github.com/alki-project/alki/blob/master/doc/index.adoc[here]
+
+Example projects can be found https://github.com/alki-project/alki-examples[here]
+
+## Authors
 
+Written by Matt Edlefsen

data/Rakefile

@@ -1,29 +1,4 @@
 require "bundler/gem_tasks"
-require 'rake/testtask'
+require 'alki/testing/tasks'
 
-Rake::TestTask.new do |t|
-  t.name = 'test:unit'
-  t.pattern = "test/unit/*_test.rb"
-end
-
-Rake::TestTask.new do |t|
-  t.name = 'test:feature'
-  t.pattern = "test/feature/*_test.rb"
-end
-
-Rake::TestTask.new do |t|
-  t.name = 'test:integration'
-  t.pattern = "test/integration/*_test.rb"
-end
-
-Rake::TestTask.new do |t|
-  t.name = 'test:page'
-  t.pattern = "test/page/*_test.rb"
-end
-
-Rake::TestTask.new do |t|
-  t.name = 'test'
-  t.pattern = "test/*/*_test.rb"
-end
-
-task default: [:test]
+task default: [:test]

data/alki.gemspec

@@ -18,9 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake", '~> 10.0'
-  spec.add_dependency "alki-dsl", "~> 0.5"
+  spec.add_dependency "alki-dsl", "~> 0.5", '>= 0.5.1'
   spec.add_dependency "alki-support", "~> 0.7"
   spec.add_dependency "concurrent-ruby", "~> 1.0"
   spec.add_dependency "ice_nine", "~> 0.11"

data/bin/bundler

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'bundler' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("bundler", "bundler")

data/bin/rake

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/doc/assemblies.adoc

@@ -17,7 +17,7 @@ Project Assemblies
 Most of the time, a project will have a single assembly, so Alki makes having a single project wide
 assembly especially easy.
 
-First. in your project's `lib` directory create a ruby file for your assembly. If your assembly is
+First, in your project's `lib` directory create a ruby file for your assembly. If your assembly is
 to be called `MyAssembly`, create `lib/my_assembly.rb`. If it's namespaced put it in a subdirectory
 as usual (i.e. `MyModule::MyAssembly` would go in `lib/my_module/my_assembly.rb`).
 
@@ -126,7 +126,6 @@ The limitiation of this is that it can only override basic values. To override m
 a block can be given to `new` allowing the full assembly DSL.
 
 ```ruby
-require 'alki'
 class MyLogger
   def initialize(io)
     @io = io
@@ -150,4 +149,4 @@ instance.util.logger.info "test"
 
 One thing of note is that elements from the assembly are accessible in overrides via the `original`
 method, as seen above. This can also be used to access the original versions of elements that have
-been overriden.
+been overriden.

data/doc/assembly_dsl.adoc

@@ -2,7 +2,7 @@ Assembly DSL
 ============
 :toc:
 
-Building Assemblies is done via a DSL that makes putting together the pieces of your project easy.
+Building Assemblies is done via a small DSL
 
 Groups (group)
 --------------
@@ -23,8 +23,7 @@ puts assembly.new.sub_group.val
 #output: hello world
 ```
 
-Scoping is also done by group, so that an element will be found by searching through parent groups until
-it is found.
+Scoping is also done by group, so that an element will be found by searching through parent groups.
 
 ```ruby
 require 'alki'
@@ -213,8 +212,7 @@ puts assembly.new.greet "Matt"
 
 Services are the key element Assemblies are typically made up of. Like the block form of `set`,
 `service` takes a name and block, which will be evaluated once on-demand and the result cached.
-One difference between the block form of `set` and `service` is that services are affected
-by overlays, whereas basic values are not.
+Whereas `set` is a lightweight element for simple values, `service` provides more functionality.
 
 Commonly a service will require the file that defines a class, and then constructs an instance of
 that class.
@@ -235,9 +233,13 @@ assembly.new.logger << "hello\n"
 ### Factories (factory)
 
 Factories are a mix between services and funcs. Like services, they take a block which is evaluated
-once. Unlike services though, that block must return a callable object (like a Proc). This object
-is then called directly when the factory is referenced. This allows you to require files or construct
-a factory object once but still run code on every reference.
+once. Unlike services though, that block must return a callable "builder" (like a Proc).
+
+If a factory is referenced as a service (i.e. no arguments) it returns a factory object
+that responds to either `#call` or `#new` and will call the builder in turn.
+
+If a factory is instead referenced like a method (i.e. with arguments) it will
+call the builder directly.
 
 ```ruby
 require 'alki'
@@ -249,6 +251,8 @@ assembly = Alki.create_assembly do
 
   service :main_logger do
     logger STDOUT
+    # -or-
+    logger.call STDOUT
   end
 end
 assembly.new.main_logger << "hello\n"
@@ -256,29 +260,23 @@ assembly.new.main_logger << "hello\n"
 #output: hello
 ```
 
-## Overlays (overlay)
-
-Overlays are a way to intercept and transform calls made to all services in a given group or it's
-sub-groups.
-
-Overlays are often most useful in groups where all services adhere to a common interface, and overlays
-can be used to perform aspect oriented programming like logging, validation, or access controls.
-
 
 ## Mounting Assemblies (mount)
 
 Other assemblies can be mounted into your Assembly using the `mount` command.
 
-The first argument is what the element should be named in the parent assembly. The optional second argument
-is the name of the assembly to be mounted. This should be formatted like a require string (relative path but
-no `.rb`) and will default to the value of the first argument. If a classified version of that name
-can't be found, Alki will attempt to `require` it, and then look for it again.
+The first argument is what the element should be named in the parent assembly.
+The optional second argument is the assembly to be mounted.
+This can either be the assembly module,
+or be a "require" string (relative path but no `.rb`).
+It defaults to the element name.
+If a string, Alki will attempt to `require` it, and then look for a matching constant.
+
 
 ```ruby
 require 'alki'
 
-# Creates OtherAssembly
-Alki.create_assembly name: 'other_assembly' do
+other_assembly = Alki.create_assembly do
   set :val, "one"
 
   # This is invalid as there is no such element as 'val2'
@@ -293,12 +291,11 @@ Alki.create_assembly name: 'other_assembly' do
   end
 end
 
-Alki.create_assembly name: 'main_assembly' do
+assembly = Alki.create_assembly do
   set :val2, "two"
-  # Mounts OtherAssembly as 'other'
-  mount :other, 'other_assembly'
+  mount :other, other_assembly
 end
-instance = MainAssembly.new
+instance = assembly.new
 puts instance.other.val
 #output: one
 
@@ -322,22 +319,186 @@ automatically in scope for overrides.
 
 ```ruby
 require 'alki'
-Alki.create_assembly name: 'other_assembly' do
+other_assembly = Alki.create_assembly do
   set :msg, nil
   func :print do
     puts msg
   end
 end
 
-Alki.create_assembly name: 'main_assembly' do
+assembly = Alki.create_assembly do
   set :val, "hello"
-  mount :other, 'other_assembly' do
+  mount :other, other_assembly do
     set :msg do
       val
     end
   end
 end
-MainAssembly.new.other.print
+assembly.new.other.print
 
 #output: hello
 ```
+
+## Overlays and Tags
+
+Overlays are a way to transparently wrap services. They work by taking the
+name of a service or a group, in which case they are applied to all services in that group,
+along with the name of an element to be used as the overlay, plus some optional arguments.
+
+When the named service is built, the overlay element will be called (with `.call`), with
+the built service object and the optional arguments, and it's result will be what's
+returned.
+
+Factories work well as overlay elements.
+
+```ruby
+require 'alki'
+
+assembly = Alki.create_assembly do
+  overlay :greeting, :exclaim, 3
+
+  service :greeting do
+    'Hello World'
+  end
+
+  factory :exclaim do
+    -> (string,count) do
+      string + ('!' * count)
+    end
+  end
+end
+
+puts assembly.new.greeting
+
+#output: Hello World!!!
+```
+
+### Tags (tag)
+
+Tags are way of adding metadata to your elements. They can either be just a name, or
+optionally carry a value
+
+```ruby
+require 'alki'
+
+assembly = Alki.create_assembly do
+  tag :tag1, with_value: 123
+  service :tagged do
+    meta[:tags]
+  end
+end
+
+puts assembly.new.tagged
+
+#output: {:with_value=>123, :tag1=>true}
+```
+
+Tags can be applied to groups to tag everything within that group
+
+```ruby
+require 'alki'
+
+assembly = Alki.create_assembly do
+  tag :tag1
+  group :grp do
+    tag :tag2
+    service :tagged do
+      meta[:tags]
+    end
+  end
+end
+
+puts assembly.new.grp.tagged
+
+#output: {:tag1=>true, :tag2=>true}
+```
+
+#### Overlaying tags (overlay_tag)
+
+Instead of overlaying services directly, it's often useful to overlay all services
+with a given tag.
+
+```ruby
+require 'alki'
+
+assembly = Alki.create_assembly do
+  overlay_tag :exclaimed, :exclaim, 3
+
+  tag :exclaimed
+  service :greeting do
+    'Hello World'
+  end
+
+  factory :exclaim do
+    -> (string,count) do
+      string + ('!' * count)
+    end
+  end
+end
+
+puts assembly.new.greeting
+
+#output: Hello World!!!
+```
+
+Factories can access the tags of the services their being called from, allowing you
+to customize the build based on what tags are present
+
+```ruby
+require 'alki'
+
+assembly = Alki.create_assembly do
+  overlay_tag :process, :process_string
+
+  tag :process, exclaim: 3
+  service :greeting do
+    'Hello World'
+  end
+
+  factory :process_string do
+    -> (string) do
+      if exclaim = meta[:tags][:exclaim]
+        string = string + ('!' * exclaim)
+      end
+      string
+    end
+  end
+end
+
+puts assembly.new.greeting
+
+#output: Hello World!!!
+```
+
+Finally, tag overlays work even across assembly mounts, allowing overlays to
+be defined in a library, and then applied by tagging services.
+
+```ruby
+require 'alki'
+
+string_processor = Alki.create_assembly do
+  overlay_tag :process, :process_string
+
+  factory :process_string do
+    -> (string) do
+      if exclaim = meta[:tags][:exclaim]
+        string = string + ('!' * exclaim)
+      end
+      string
+    end
+  end
+end
+
+assembly = Alki.create_assembly do
+  mount :string_processor, string_processor
+
+  tag :process, exclaim: 3
+  service :greeting do
+    'Hello World'
+  end
+end
+
+puts assembly.new.greeting
+
+#output: Hello World!!!
+```