alki 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 91b0f6c880177b0e4be1c5228c92b0295db5742a
-  data.tar.gz: 6c781108545400031137040024b040c3a67d9b16
+  metadata.gz: 30b3e6d184beebdc00446b13b4930d47d32151df
+  data.tar.gz: 98249b15e58962ab44737b9e54199f8690938407
 SHA512:
-  metadata.gz: cc46916b429be7d64b76b2e9e93d086493699d8303607d248471a55fed9da1ab13e7c01bc7b2b700a44c71180943c53fb766b72d50b3dd10dd75ec700e6816cc
-  data.tar.gz: e17b68e68390ea600d2d5f2dabe48029696537d2d8ded480eec57cb1a6bf6601dc4035aaf666311ab63f3a28684dac9f571b2e8746e11885b204cfd5c2ccbe09
+  metadata.gz: df40acd78708b8a0371f5191f1b5160c4d09e9348e92c237791761528a22552f3212c7dd14759c555b20d5364def4cd1976eaa12ad90690d3d9b81a7c5e27670
+  data.tar.gz: 24bc23ef4c32c0b16a6e63a0386c3a767bcc9fc0a2393b8197c9d942e4f9ebad6bc97b394d1d142c060cc39371e42d6fc2edeb6d72a51035fd12dad836babc8c

data/README.adoc

@@ -1,12 +1,114 @@
 # What is Alki?
+:toc:
 
-Alki is a framework for creating projects that are modular, testable, and well organized.
+Alki is a small framework for writing Ruby projects, providing a powerful dependency injection system with
+helpers for testing, creating executables, and easy to use libraries.
 
-It's goal is to remove uncertainty and friction when building Ruby projects, allowing developers to focus on implementing business logic.
+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.
 
-Best place to start would be to check out some examples:
+Alki tries to combine the 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].
 
-* https://github.com/alki-project/alki-example
-* https://github.com/alki-project/alki/tree/master/test/fixtures/example
+Documentation can be found at https://github.com/alki-project/alki/blob/master/doc/index.adoc
+
+## Getting Started
+
+Install from rubygems
+
+    gem install alki
+
+Setting up Alki in your project requires only created 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.
+
+.Example project
+```
+$ cd <project dir>
+$ alki init --console <project name>
+```
+## Example
+
+To demonstrate the basic features of Alki, this will go through the creation of
+a simple example project.
+
+To get started, a new project should be created.
+
+```
+$ mkdir example
+$ cd example
+$ alki init --console example
+```
+
+### First Service
+
+Open up `config/assembly.rb` in your favorite text editor and add a simple log
+service as an example. The service definition should require the files it needs and
+then construct an object.
+
+.config/assembly.rb
+```ruby
+Alki do
+  mount :console, 'alki/console', name: 'example'
+
+  service :log do
+    require 'logger'
+    Logger.new STDERR
+  end
+end
+```
+
+To test, we can open up the console and interact with our new service.
+
+```bash
+$ bin/console
+example> log.info "test message"
+I, [<timestamp>]  INFO -- : test message
+=> true
+test> exit
+```
+
+### Adding Settings
+
+Many times in a project there will end with a lot of configuration settings or magic
+numbers sprinkled throughout your code, maybe pulled from `ENV` or just set directly
+as constants. Alki provides a simple way to centralize them. By convention this is done
+by creating a `config/settings.rb` and loading it into your Assembly.
+
+To demonstrate we can pull the log io (`STDERR`) out of our main assembly and add it
+to our settings.
+
+.config/settings.rb
+```ruby
+Alki do
+  set :log_io, STDERR
+end
+```
+Now we can load our settings file in our assembly config (`load :settings`) and use
+the setting in our log service.
+
+.config/assembly.rb
+```ruby
+Alki do
+  load :settings
+  mount :console, 'alki/console', name: 'example'
+
+  service :log do
+    require 'logger'
+    Logger.new settings.log_io
+  end
+end
+```
+
+### Adding your own Classes
+
+Generally, you're not just going to be using other people's classes. Alki doesn't have any requirements as to
+where your classes need to go, but conventionally they can be placed under `lib/<project-name>/`.
+
+The Alki style of writing a Class is to only `require` external libraries, or utility files in your class files.
+All of the "glue" that ties your code together can instead be put in your assembly definition. This allows you
+to modularize and loosely couple your programs.
 
-Docs can be found at https://github.com/alki-project/alki/blob/master/doc/index.adoc

data/alki.gemspec

@@ -21,6 +21,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake", '~> 10.0'
   spec.add_dependency "minitest", "~> 5.9", '>= 5.9.1'
-  spec.add_dependency "alki-dsl", "~> 0.3", '>= 0.3.1'
-  spec.add_dependency "alki-support", "~> 0.5"
+  spec.add_dependency "alki-dsl", "~> 0.3", '>= 0.3.3'
+  spec.add_dependency "alki-support", "~> 0.6"
 end

data/bin/alki

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'alki' 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("alki", "alki")

data/config/dsls.rb

@@ -1,4 +1,4 @@
 Alki do
-  register_lib_dir 'alki/dsls/assembly_types', 'alki/dsls/assembly_type_dsl'
+  register_lib_dir 'alki/assembly/types', 'alki/dsls/assembly_type'
   register_lib_dir 'alki/dsls', 'alki/dsls/dsl'
-end
+end

data/doc/assembly_dsl.adoc

@@ -227,7 +227,7 @@ assembly = Alki.create_assembly do
     Logger.new STDOUT
   end
 end
-assembly.new.logger << "hello"
+assembly.new.logger << "hello\n"
 
 #output: hello
 ```
@@ -251,7 +251,7 @@ assembly = Alki.create_assembly do
     logger STDOUT
   end
 end
-assembly.new.main_logger << "hello"
+assembly.new.main_logger << "hello\n"
 
 #output: hello
 ```
@@ -265,9 +265,9 @@ 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)
+## Mounting Assemblies (mount)
 
-Other assemblies can be mounted into your Assembly using the `assembly` command.
+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
@@ -296,7 +296,7 @@ end
 Alki.create_assembly name: 'main_assembly' do
   set :val2, "two"
   # Mounts OtherAssembly as 'other'
-  assembly :other, 'other_assembly'
+  mount :other, 'other_assembly'
 end
 instance = MainAssembly.new
 puts instance.other.val
@@ -331,7 +331,7 @@ end
 
 Alki.create_assembly name: 'main_assembly' do
   set :val, "hello"
-  assembly :other, 'other_assembly' do
+  mount :other, 'other_assembly' do
     set :msg do
       val
     end

data/exe/alki

@@ -0,0 +1,275 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+require 'optparse'
+require 'alki/support'
+
+valid_addons = ["console"]
+
+options = {
+  config_dir: nil,
+  primary_config: nil,
+  addons: [],
+  project_dir: Dir.pwd,
+}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: alki init PROJECT_NAME [options]"
+
+  opts.on("-a", "--add[=ADDON]", "Add addon to project. Valid addons: #{valid_addons.join(', ')}") do |v|
+    unless valid_addons.include? v
+      puts "Invalid addon: #{v}"
+      exit 1
+    end
+    options[:addon] |= [v]
+  end
+
+  opts.on('-d','--directory=DIRECTORY', 'Project root, defaults to the current working directory') do |v|
+    options[:project_dir] = v
+  end
+
+  opts.on("-c", "--config=DIECTORY", "Override config dir (default \"config\")") do |v|
+    options[:config_dir] = v
+  end
+
+  opts.on("-p", "--primary=PRIMARY_CONFIG", "Override primary config (default \"assembly\")") do |v|
+    options[:primary_config] = v
+  end
+end
+
+parser.parse!
+
+if ARGV.size != 2 || ARGV[0] != "init"
+  puts parser.banner
+  exit 1
+end
+
+unless ARGV[1] =~  %r{^[a-z0-9_]+(/[a-z0-9_]+)*$}
+  puts "Invalid project name. May only consist of lowercase letters, numbers, underscores, and forward slashes"
+  exit 1
+end
+
+
+
+class AlkiFileWriter
+  def initialize(root_dir)
+    @root_dir = root_dir
+    @changes = []
+    @triggers = []
+  end
+
+  def create(file,contents)
+    @changes << [:create,file: file,contents: contents,opts: {}]
+  end
+
+  def create_exec(file,contents)
+    @changes << [:create,file: file,contents: contents,opts: {exec: true}]
+  end
+
+  def check_create(file:, contents:, opts:)
+    path = abs_path( file)
+    if File.exists? path
+      if File.read(path) == contents
+        :skip
+      end
+    end
+  end
+
+  def desc_create(file:, contents:, opts: {})
+    path = abs_path( file)
+    if opts[:exec]
+      adj = "executable "
+    end
+    if File.exists? path
+      "Overwriting #{adj}#{file}!"
+    else
+      "Create #{adj}#{file}"
+    end
+  end
+
+  def do_create(file:, contents:, opts: {})
+    path = abs_path( file)
+    FileUtils.mkdir_p File.dirname(path)
+    File.write path, contents
+    FileUtils.chmod '+x', path if opts[:exec]
+  end
+
+  def opt_create(file,contents)
+    @changes << [:opt_create,file: file,contents: contents]
+  end
+
+  def check_opt_create(file:, contents:)
+    if File.exists? abs_path( file)
+      :skip
+    end
+  end
+
+  def desc_opt_create(opts)
+    desc_create opts
+  end
+
+  def do_opt_create(opts)
+    do_create opts
+  end
+
+  def add_line(file,line,opts={})
+    @changes << [:add_line,file: file,line: line,opts: opts]
+  end
+
+  def check_add_line(file:,line:,opts:)
+    if File.exists? abs_path(file)
+      File.open(file) do |f|
+        if opts[:after]
+          found = until f.eof?
+            break true if f.readline.chomp == opts[:after]
+          end
+          unless found
+            puts "File \"#{file}\" doesn't contain required line #{opts[:after]}"
+            return :abort
+          end
+        end
+        until f.eof?
+          l = f.readline
+          if opts[:match] ? l.chomp.match(opts[:match]) : (l.chomp == line)
+            return :skip
+          end
+        end
+      end
+    else
+      unless @changes.find {|c| [:create,:opt_create].include?(c[0]) && c[1][:file] == file}
+        puts "File \"#{file}\" doesn't exist!"
+        return :abort
+      end
+    end
+  end
+
+  def desc_add_line(file:,line:,opts:)
+    "Add line \"#{line}\" to #{file}"
+  end
+
+  def do_add_line(file:,line:,opts:)
+    if opts[:after]
+      File.write file, File.read(file).sub(/^#{Regexp.quote(opts[:after])}\n/){|m| m + line + "\n"}
+    else
+      File.open(file,'a') do |f|
+        f.puts line
+      end
+    end
+  end
+
+  def trigger(file,cmd)
+    @triggers << [file, cmd]
+  end
+
+  def check_trigger(changes,file)
+    changes.find {|c| c[1][:file] == file}
+  end
+
+  def desc_trigger(cmd:)
+    "Run \"#{cmd}\""
+  end
+
+  def do_trigger(cmd:)
+    system cmd
+  end
+
+  def check_changes
+    puts "Checking preconditions..."
+    abort = false
+    unless Dir.exists?(@root_dir)
+      puts "Root dir doesn't exist"
+      exit 1
+    end
+    do_changes = []
+    @changes.each do |(type,args)|
+      res = send "check_#{type}", args
+      abort = true if res == :abort
+      do_changes << [type,args] unless res == :skip
+    end
+    @triggers.each do |(file,cmd)|
+      if check_trigger do_changes, file
+        do_changes << [:trigger,cmd: cmd]
+      end
+    end
+    exit 1 if abort
+    do_changes
+  end
+
+  def print_overview(changes)
+    puts "Overview of changes to be made:"
+
+    changes.each do |(type,args)|
+      desc = send "desc_#{type}", args
+      puts "  #{desc}" if desc
+    end
+    print "Proceed? "
+    resp = STDIN.gets.chomp
+    unless resp =~ /^y(es?)?/i
+      puts "Aborting"
+      exit
+    end
+  end
+
+  def write
+    puts "Using project root: #{@root_dir}\n"
+    do_changes = check_changes
+    print_overview do_changes
+
+    puts "Writing changes..."
+    do_changes.each do |(type,args)|
+      send "do_#{type}", args
+    end
+    puts "Done"
+  end
+
+  def abs_path(p)
+    File.expand_path(p,@root_dir)
+  end
+end
+
+project_name = ARGV[1]
+
+fw = AlkiFileWriter.new config[:project_dir]
+
+config_dir = options[:config_dir] || 'config'
+primary_config = options[:primary_config] || 'assembly'
+primary_config_path = File.join(config_dir,primary_config+'.rb')
+fw.opt_create primary_config_path, <<END
+Alki do
+  # Assembly config goes here
+end
+END
+
+opts = []
+opts << "config_dir: '#{options[:config_dir]}'" if options[:config_dir]
+opts << "primary_config: '#{options[:primary_config]}'" if options[:primary_config]
+unless opts.empty?
+  opt_str = " #{opts.join(', ')}"
+end
+fw.create "lib/#{project_name}.rb", <<END
+require 'alki'
+Alki.project_assembly!#{opt_str}
+END
+
+fw.opt_create "Gemfile", <<END
+source "https://rubygems.org"
+END
+
+fw.trigger 'Gemfile', 'bundle install'
+
+fw.add_line "Gemfile", "gem 'alki'", match: /^gem ['"]alki['"]/
+
+if options[:addons].include? "console"
+  fw.add_line "Gemfile", "gem 'alki-console'", match: /^gem ['"]alki-console['"]/
+
+  name = project_name.tr('/','-')
+  fw.add_line primary_config_path, "  mount :console, 'alki/console', name: '#{name}'", match: /^\s*assembly :console/, after: 'Alki do'
+
+  fw.create_exec 'bin/console', <<END
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'alki/bin'
+require '#{project_name}'
+#{Alki::Support.classify(project_name)}.new.console.run
+END
+end
+
+fw.write

data/lib/alki/assembly/builder.rb

@@ -0,0 +1,113 @@
+require 'alki/assembly'
+require 'alki/class_builder'
+require 'alki/dsl'
+require 'alki/support'
+
+module Alki
+  module Assembly
+    class Builder
+      def initialize
+        @config_dir = nil
+        @assembly_name = nil
+        @definition = nil
+      end
+
+      attr_reader :config_dir, :assembly_name, :definition
+
+      def self.build(opts={},&blk)
+        new.build(opts,&blk)
+      end
+
+      def build(opts={},&blk)
+        build_assembly blk if blk
+        if opts[:config_dir]
+          context = if opts[:project_assembly]
+            File.dirname opts[:project_assembly]
+          else
+            Dir.pwd
+          end
+          @config_dir = File.expand_path opts[:config_dir], context
+        end
+        set_assembly_name opts[:name] if opts[:name]
+        setup_project_assembly opts[:project_assembly] if opts[:project_assembly]
+        register_config_directory if @config_dir
+        if blk
+          build_assembly blk
+        else
+          load_assembly_file opts[:primary_config]
+        end
+        build_empty_assembly unless definition
+        build_class
+      end
+
+      def setup_project_assembly(path)
+        root = Alki::Support.find_root(path) do |dir|
+          File.exists?(File.join(dir,'config','assembly.rb')) ||
+            File.exists?(File.join(dir,'Gemfile')) ||
+            !Dir.glob(File.join(dir,'*.gemspec')).empty?
+        end
+        if root
+          unless @config_dir
+            config_dir = File.join(root,'config')
+            @config_dir = config_dir if File.exists? config_dir
+          end
+
+          unless @assembly_name
+            lib_dir = File.join(root,'lib')
+            name = Alki::Support.path_name path, lib_dir
+            unless name
+              raise "Can't auto-detect name of assembly"
+            end
+            set_assembly_name name
+          end
+        end
+      end
+
+      def set_assembly_name(name)
+        @assembly_name = name
+      end
+
+      def register_config_directory
+        opts = {config_dir: @config_dir}
+        opts[:prefix] = File.join(@assembly_name,'alki_config') if @assembly_name
+        Alki::Dsl.register_dir @config_dir, 'alki/dsls/assembly', opts
+      end
+
+      def load_assembly_file(name = nil)
+        name ||= 'assembly'
+        if @config_dir
+          assembly_config_path = File.join(@config_dir,"#{name}.rb")
+          if File.exists? assembly_config_path
+            @definition = Alki::Dsl.load(assembly_config_path)[:class]
+            true
+          end
+        end
+      end
+
+      def build_empty_assembly
+        build_assembly ->{}
+      end
+
+      def build_assembly(blk)
+        @definition = Alki::Dsl.build('alki/dsls/assembly', config_dir: @config_dir, &blk)[:class]
+      end
+
+      def build_class
+        definition = @definition
+        Alki::ClassBuilder.build(
+          prefix: '',
+          name: @assembly_name,
+          class_modules: [Alki::Assembly],
+          type: :module,
+          class_methods: {
+            definition: {
+              body: ->{
+                definition
+              }
+            },
+          }
+        )
+      end
+    end
+  end
+end