alki 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31a32ce28977b35ce72bab1992d4512c7ea33f44
-  data.tar.gz: c6ab121484e99b437aaae6390db983d83a011cc7
+  metadata.gz: 91b0f6c880177b0e4be1c5228c92b0295db5742a
+  data.tar.gz: 6c781108545400031137040024b040c3a67d9b16
 SHA512:
-  metadata.gz: bd1da1b284b8caa1d75a32ac5e199f5f64e504213de1abeedb694e6f6fca517633992b8f2572129b71d329ed0069de2d698b89c0dd2f395a72d49243dbe2032c
-  data.tar.gz: fd7e999ffc561b91e6452bd859f8f8783fd0a90f097a703febd7746d837227717fa2bfafdaac310903eecef08090d1b2fd834444682b49a38ccdb37dac404a10
+  metadata.gz: cc46916b429be7d64b76b2e9e93d086493699d8303607d248471a55fed9da1ab13e7c01bc7b2b700a44c71180943c53fb766b72d50b3dd10dd75ec700e6816cc
+  data.tar.gz: e17b68e68390ea600d2d5f2dabe48029696537d2d8ded480eec57cb1a6bf6601dc4035aaf666311ab63f3a28684dac9f571b2e8746e11885b204cfd5c2ccbe09

data/{README.ad → README.adoc}

@@ -4,9 +4,9 @@ Alki is a framework for creating projects that are modular, testable, and well o
 
 It's goal is to remove uncertainty and friction when building Ruby projects, allowing developers to focus on implementing business logic.
 
-# Synopsis
-
 Best place to start would be to check out some examples:
 
 * https://github.com/alki-project/alki-example
 * https://github.com/alki-project/alki/tree/master/test/fixtures/example
+
+Docs can be found at https://github.com/alki-project/alki/blob/master/doc/index.adoc

data/doc/{assemblies.ad → assemblies.adoc}

@@ -1,14 +1,25 @@
 Assemblies
 ==========
+:toc:
+
+If a set of classes are your raw materials, an Assembly is the finished product,
+ready to be used.
+
+To get there, you provide Alki with your assembly definition, which acts as the instructions for
+how to piece together your classes and objects. Assemblies are made up of elements, which are groups
+of other elements, or various value types like services and factories.
+
+Assembly definitions are written in a simple DSL.
 
 Project Assemblies
 ------------------
 
-Most of the time, a project will have a single assembly. Alki makes doing this easy.
+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
-to be called `MyAssembly`, create `lib/my_assembly.rb`. If it's namespaced but it in a subdirectory
-as usual, `MyModule::MyAssembly` would go in `lib/my_module/my_assembly.rb`
+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`).
 
 Your assembly file just needs two lines:
 
@@ -20,7 +31,8 @@ Alki.project_assembly!
 It will detect the project root and what class name it should create automatically.
 
 Second, a `config` directory must be created in the project root, and in that directory an `assembly.rb`
-file should be created. It should be a normal Alki loader block.
+file should be created. It should contain an `Alki do ... end` block which contains the top level
+definition for your Assembly.
 
 ```ruby
 Alki do
@@ -47,6 +59,7 @@ It should be called with a block that contains the assembly DSL. It will return
 be used directly or assigned to a constant.
 
 ```ruby
+require 'alki'
 assembly = Alki.create_assembly do
   set :msg, "hello world"
   func :run do
@@ -80,7 +93,7 @@ assembly = Alki.create_assembly do
 end
 ```
 
-Once can use the logger service like so:
+One can use the logger service like so:
 
 ```ruby
 instance = assembly.new
@@ -91,12 +104,12 @@ instance.util.logger.info "test"
 
 ### Overrides
 
-Assembly overrides provide a way to do configure or customize an Assembly when
+Assembly overrides provide a way to configure or customize an Assembly when
 constructing an instance.
 
 For example, using the assembly created above, one might want to change the IO object logged to.
 
-The simplist way to do this is to provide a hash of values which will set values (as if the `set`
+The simplist way to do this is to provide a hash which will override values in the assembly (as if the `set`
 command was called in the DSL):
 
 ```ruby
@@ -113,6 +126,7 @@ 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
@@ -134,5 +148,6 @@ instance.util.logger.info "test"
 # output: INFO test
 ```
 
-One thing of note is that elements from the assembly are accessibly via the `original` method.
-This can also be used to access the original versions of elements that have been overriden.
+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.

data/doc/{assembly_dsl.ad → assembly_dsl.adoc}

@@ -1,10 +1,11 @@
 Assembly DSL
-===========
+============
+:toc:
 
 Building Assemblies is done via a DSL that makes putting together the pieces of your project easy.
 
-Groups
-------
+Groups (group)
+--------------
 
 Groups are the basic way of organizing the elements of your Assembly. Creating elements at the top
 level of an Assembly will place them in a root group, but subgroups are easily created via the `group`
@@ -18,30 +19,43 @@ assembly = Alki.create_assembly do
   end
 end
 puts assembly.new.sub_group.val
+
+#output: hello world
 ```
 
-Scoping is also done by group, so that an element will be found by moving up parent groups until
+Scoping is also done by group, so that an element will be found by searching through parent groups until
 it is found.
 
 ```ruby
 require 'alki'
 assembly = Alki.create_assembly do
   set :val, "one"
+  func :print do
+    puts val
+  end
+
   group :g1 do
     set :val, "two"
+
     group :g2 do
       func :print do
         puts val
       end
     end
+
   end
 end
+
+assembly.new.print
+
+#output: one
+
 assembly.new.g1.g2.print
 
 #output: two
 ```
 
-=== Loading groups
+=== Loading groups (load)
 
 Groups can also be loaded from other config files via the `load` command.
 
@@ -52,6 +66,7 @@ Alki do
 end
 ```
 
+.main code
 ```ruby
 require 'alki'
 assembly = Alki.create_assembly config_dir: 'config' do
@@ -69,6 +84,85 @@ assembly.new.print
 Values
 ------
 
+Values are how you add functionality to your Assembly. There are different types of values, but they
+all share a number of common features.
+
+### On-Demand
+
+Values are only built when referenced, on demand. This means even if you have a very large assembly
+only the things you actually use in a given run will be created, or often even `require`-d. It also
+means that all values will automatically be built in the correct order to satisfy dependencies.
+
+### Scope
+
+When providing a block for a value, the block will be executed in a special context with some
+additional helper methods.
+
+The most important methods available are other elements that are "in scope". For example, a value can
+reference a sibling element in the same group, or any value in any ancestor group. The order that
+elements are defined does not effect what is in scope. All other elements are out of scope, but can
+usually still be referenced by finding an ancestor group that 'is' in scope, and then drilling down
+from there.
+
+```ruby
+require 'alki'
+assembly = Alki.create_assembly config_dir: 'config' do
+  set :val1, "1"
+  group :main do
+    group :sub_group do
+      set :val2, "2"
+    end
+
+    set :values do
+      [
+        val1, # OK
+      # val2, # ERROR
+        sub_group.val2, # OK
+        val3, # OK
+      # val4, # ERROR
+        other_group.val4, #OK
+      ].join('')
+    end
+
+    set :val3, "3"
+  end
+
+  group :other_group do
+    set :val4, "4"
+  end
+
+end
+puts assembly.new.main.values
+
+#output: 1234
+```
+
+### Helpers
+
+In addition to elements in scope, there are some helper methods that are always available in value
+blocks.
+
+[horizontal]
+
+assembly:: This will return the root group of the assembly the element is defined in.
+
+root:: This will return the root group of the 'top most' assembly being run. If only a single
+assembly is being run, this will be the same as `assembly` but if the element being run is in
+an assembly that has been mounted into another assembly, they will differ.
+
+lookup(path):: This can be used to reference an element by a string path (using periods (`.`) to
+drill down into groups). If called directly it will lookup using the local scope. It is also available
+as a method on all groups, so `assembly.lookup(path)` would lookup an element starting from the root
+of the assembly.
+
+lazy(path):: This works the same as `lookup`, but with an important difference: Instead of doing the
+lookup immediately, it will instead return a "proxy" object, which will do the lookup the first time
+a method is called on the proxy object, and then delegate all method calls to the actual element. This
+can be used to handle circular references in services.
+
+Value Types
+-----------
+
 There are four types of elements loosely categorized as "values".
 
 ### Basic Values (set)
@@ -162,7 +256,7 @@ assembly.new.main_logger << "hello"
 #output: hello
 ```
 
-### Overlays (overlay)
+## Overlays (overlay)
 
 Overlays are a way to intercept and transform calls made to all services in a given group or it's
 sub-groups.
@@ -171,24 +265,29 @@ Overlays are often most useful in groups where all services adhere to a common i
 can be used to perform aspect oriented programming like logging, validation, or access controls.
 
 
-### Assemblies (assembly)
+## Assemblies (assembly)
 
 Other assemblies can be mounted into your Assembly using the `assembly` command.
 
-The first argument is what it should be named in your assembly. The optional second argument
-is the name of the assembly. This should be formatted like a require string (relative path but
+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, it will attempt to `require` it, and then try again.
+can't be found, Alki will attempt to `require` it, and then look for it again.
 
 ```ruby
 require 'alki'
+
+# Creates OtherAssembly
 Alki.create_assembly name: 'other_assembly' do
   set :val, "one"
 
+  # This is invalid as there is no such element as 'val2'
   set :invalid_val2 do
     val2
   end
 
+  # Normally, this would also be invalid, but if mounted
+  # in an assembly that has a 'val2' element, this works.
   set :root_val2 do
     root.val2
   end
@@ -196,13 +295,15 @@ end
 
 Alki.create_assembly name: 'main_assembly' do
   set :val2, "two"
+  # Mounts OtherAssembly as 'other'
   assembly :other, 'other_assembly'
 end
 instance = MainAssembly.new
 puts instance.other.val
 #output: one
 
-# Can't access val2 in main assembly
+# Even though val2 exists in MainAssembly, it is not directly accessibly to elements
+# within OtherAssembly
 begin
   puts instance.other.invalid_val2
 rescue => e
@@ -210,7 +311,7 @@ rescue => e
 end
 # output: undefined local variable or method 'val2'
 
-# This works, because root returns the root assembly
+# This works, because root returns the root assembly, which has a 'val2' element
 puts instance.other.root_val2
 #output: two
 ```

data/doc/{index.ad → index.adoc}

@@ -1,15 +1,16 @@
 Alki
 ====
+:toc:
 
 Alki is a framework for creating projects that are modular, testable, and well organized.
 
 It's goal is to remove uncertainty and friction when building Ruby projects, allowing developers to focus on implementing business logic.
 
 :leveloffset: 1
-include::projects.ad[]
+include::projects.adoc[]
 
 :leveloffset: 1
-include::assemblies.ad[]
+include::assemblies.adoc[]
 
 :leveloffset: 1
-include::assembly_dsl.ad[]
+include::assembly_dsl.adoc[]

data/doc/{projects.ad → projects.adoc}

@@ -1,5 +1,6 @@
 Setting up Alki Projects
 ========================
+:toc:
 
 Generally, projects that use alki work the same as normal Ruby projects but there are a couple of
 guidelines to make life easier.

data/lib/alki/dsls/assembly_types/assembly.rb

@@ -58,7 +58,7 @@ Alki do
 
     def main_data
       assembly_path = data[:prefix] ? data[:prefix].dup : []
-      {scope: {assembly: assembly_path, root: []}, overlays: []}
+      {scope: {assembly: assembly_path, root: [], config_dir: (assembly_path + [:config_dir])}, overlays: []}
     end
 
     def override

data/lib/alki/feature_test.rb

@@ -0,0 +1,7 @@
+require 'alki/test'
+
+feature_test_helper = File.join(Alki::Test.tests_root,'feature_test_helper.rb')
+
+if File.exists? feature_test_helper
+  require feature_test_helper
+end

data/lib/alki/test.rb

@@ -1,5 +1,4 @@
-require 'bundler'
-Bundler.setup(:default,:test)
+Bundler.require(:test)
 require 'minitest/autorun'
 require 'alki/dsl'
 
@@ -41,8 +40,8 @@ unless $LOAD_PATH.include? Alki::Test.lib_dir
   $LOAD_PATH.unshift Alki::Test.lib_dir
 end
 
-test_helper_dir = File.join(Alki::Test.tests_root,'test_helper.rb')
+test_helper = File.join(Alki::Test.tests_root,'test_helper.rb')
 
-if File.exists? test_helper_dir
-  require test_helper_dir
+if File.exists? test_helper
+  require test_helper
 end

data/lib/alki/version.rb

@@ -1,3 +1,3 @@
 module Alki
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alki
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Matt Edlefsen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-05 00:00:00.000000000 Z
+date: 2016-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -103,14 +103,14 @@ files:
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
-- README.ad
+- README.adoc
 - Rakefile
 - alki.gemspec
 - config/dsls.rb
-- doc/assemblies.ad
-- doc/assembly_dsl.ad
-- doc/index.ad
-- doc/projects.ad
+- doc/assemblies.adoc
+- doc/assembly_dsl.adoc
+- doc/index.adoc
+- doc/projects.adoc
 - lib/alki.rb
 - lib/alki/assembly.rb
 - lib/alki/assembly_builder.rb
@@ -126,6 +126,7 @@ files:
 - lib/alki/dsls/assembly_types/overlay.rb
 - lib/alki/dsls/assembly_types/value.rb
 - lib/alki/dsls/service.rb
+- lib/alki/feature_test.rb
 - lib/alki/overlay_delegator.rb
 - lib/alki/override_builder.rb
 - lib/alki/service_delegator.rb