sho 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 125faf4a77feba4430c913006c9a0c594032492c
+  data.tar.gz: 48b7aef74a0acd727c7cfa848fa95f932e22504a
+SHA512:
+  metadata.gz: 8bf09de4470247c23f2cd1ab956d01996337c8e654337cd53fe20f8331bdab50027dd7c0d46ee0a40edf1baad9dc88bbec8550088f6c3a0293a4754119da5e29
+  data.tar.gz: a4f0689ca99551d70ef474b90d856321fc1894918ac280e9931b48cf57da8e1e46d551fec964b5fbfc689d38f16e6d467e8e93cf4f86c1f40db85ba53d03d626

data/README.md

@@ -0,0 +1,150 @@
+# Sho: post-framework view library
+
+[![Gem Version](https://badge.fury.io/rb/sho.svg)](http://badge.fury.io/rb/sho)
+[![Build Status](https://travis-ci.org/zverok/sho.svg?branch=master)](https://travis-ci.org/zverok/sho)
+
+**Sho** is an experimental **post-framework** Ruby view library. It is based on Tilt and meant to provide entire view layer for a web application (based on any framework or completely frameworkless).
+
+<sup>"Sho?" ("Шо?") is a Kharkiv dialecticism, meaning "What?", typically in a slightly aggressive manner. It is chosen as a library name because it is close to "show" in a written and spoken form (and also because "What?" is expected typical reaction to the library).</sup>
+
+**Post-framework** means Sho behaves as a decent _library_, neither implying nor forcing _any_ kind of conventions for your code layout and structure.
+
+Currently, if you want your app architecture not to follow strict framework's _frame_, you can take ROM or Sequel for _data layer_; Sinatra, Roda, or Grape for _routing layer_; but for _view layer_, the situation seems to be different. Typical "views" part of the application (say, with Rails, Hanami, Padrino) is bound to a lot of conventions (like "it will look for the corresponding template in that folders") and global configuration, and tightly coupled with routes/controllers ("if you want data from controller to be passed to view, you mark it so an so").
+
+**Sho** is an experiment to provide view layer that is "just Ruby" (= follows the regular intuitions of _Ruby_ programmer, not introducing some hidden conventions that are not deductible from the code) and reuses regular Ruby concepts for code sharing, parameters passing and flow structuring instead of introducing its own concepts like "helpers", "exposures", "locals" (completely unlike local variables!) and so on.
+
+## Basic synopsis
+
+```ruby
+# in any class you want
+include Sho
+
+sho.template :name, 'path/to/template.erb', :param1, param2: default_value
+```
+
+This creates instance method with a signature¹ `YourClass#name(param1:, param2: default_value)`, which, when called, renders the template from `path/to/template.erb`.
+
+<sup>¹Due to metaprogramming limitations, real signature of method would be `name(**params)` and check of mandatory params and assignment of defaults is performed by Sho.</sup>
+
+You can think about the template as a _method body_, which immediately answers a lot of questions:
+
+* **What context the template is evaluated in?** Like any method: in context of the instance of the class, where the method is defined.
+* **What names are available in the template?** The same as in any methods: parameters, and other methods/variables of the instance.
+* **How do I do share "helper" code with several templates?** Just in a regular Ruby: extract it to a module, include the module in several classes with views. Or make the base class and inherit from it. Or use any other code sharing technique you are fond of.
+* **How do I do "partials" (render one template from another)?** The same as when you want to call one method from another one: just call it.
+  ```ruby
+  # In `user.rb`
+  sho.template :render, 'user.slim'
+  # That would be "partial":
+  sho.template :status_with_popup, 'user/_status_with_popup.slim'
+  ```
+  ```slim
+  / In `user.slim` (think of it as a body for `User#render` method):
+  p
+    span.name = name
+    / Call of a "partial":
+    span.status = status_with_popup
+  ```
+* **How do I test it? How do I set all the context for testing?** Just as with regular method: just create an instance, and call the method, and test the result.
+* **But where do I put this method?** Wherever you wish! Sho does NOT insist on any particular architecture or code layout, which means you can experiment and evaluate several options, like:
+  * embed rendering in controller/Sinatra app (or even model, if you want to be really naughty today!) for the very first 30-lines-long prototype, then move it elsewhere (like "Extract Method" refactoring pattern, you know?)
+  * embed rendering in your service (operation) objects, so
+  * make Users::List class with `#html`, `#atom` and `#json` methods and use it like `Users::List.new(scope).send(request.format)` or `User::List.send(request.format, scope)`
+  * make `Trailblazer::Cells`-like one-class-per-template objects to call them like `Users::HtmlList.new(scope).()`
+  * ...switch between several of the approaches, or even combine them in the same app!
+
+## Implementation details
+
+**Where should I store the templates?**
+
+Sho doesn't have any global configuration for "templates folder", neither convention for "templates are in `app/views/<current_class_name>`" or something like that. `template` method just looks for templates relative to current working folder (`Dir.pwd`). As it could be tiresome to write `app/views/blah/blah/blah/blah.slim` for each and every method, there is `sho.base_folder = ` class-level setting:
+
+```ruby
+# Before
+sho.template :profile, 'app/views/users/profile.slim'
+sho.template :icon, 'app/views/users/icon.slim'
+
+# After
+sho.base_folder = 'app/views/users'
+sho.template :profile, 'profile.slim'
+sho.template :icon, 'icon.slim'
+
+# If all of your classes and templates are in the same `app/view`, further shortcutting is
+# your own responsibility, like:
+
+sho.base_folder = VIEWS_BASE + '/users'
+```
+
+Another interesting approach that is made easy by Sho:
+```ruby
+# In app/view_models/users.rb
+
+# It is like require_relative, template should be stored at
+# app/view_models/users/profile.slim
+sho.template_relative :profile, 'users/profile.slim'
+```
+
+The idea is: as `ViewModels::Users` have `profile.slim` as a `#profile` method body, it is this class' implementation details, so, there is no point to store it in a completely different folder.
+
+**What about layouts?**
+
+**Sho** supports concept of layout with `:_layout` param. It accepts method name, and supposes this method will call `yield` at some point:
+
+```ruby
+# in app/view_models/users.rb
+sho.template_relative :list, 'users/list.slim', _layout: :main_layout
+sho.template :main_layout, 'app/views/main_layout.slim'
+```
+
+Sharing of the layout between several classes could be done in the same way as sharing of any other methods: extract it to a common module, and include wherever you like.
+
+**Small-scale usage of the library**
+
+As Sho is a _library_, not a framework, it doesn't require you to switch to Sho-only code immediately and completely. You can try it in some parts of your system, or just in one class. One useful idea is to use it in decorators (like [draper](https://github.com/drapergem/draper)), and Sho provides `inline_template` for this kind of usage:
+
+```ruby
+class RatingDecorator < Draper::Decorator
+  # ...
+
+  # before:
+  def row
+    h.content_tag(:tr,
+      h.safe_join([
+        h.content_tag(:th, "Rated by #{user.name}"),
+        h.content_tag(:td, stars),
+        h.content_tag(:td, rated_at)
+      ]),
+      class: 'rating'
+    )
+  end
+
+  # after:
+  include Sho
+
+  sho.inline_template :row,
+    slim: <<~SLIM
+      tr.rating
+        th
+          | Rated by
+          = user.name
+        td = stars
+        td = rated_at
+    SLIM
+end
+```
+
+**Template caching**
+
+Sho creates Tilt templates at a moment of the method definition. This seems to lead to most natural behavior: the templates are found and cached at a moment of code loading/reloading (whatever reloader you use).
+
+## Library status
+
+It is fresh and experimental. Tested, documented and stuff, but still not extensively used in production. Nothing guaranteed, but I'll be happy to have at least a meaningful discussion started.
+
+## Author
+
+[Victor Shepelev aka @zverok](https://zverok.github.io)
+
+## License
+
+MIT

data/lib/sho/argument_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Sho
+  # @private
+  class ArgumentValidator
+    def initialize(*mandatory, **optional)
+      mandatory.all? { |m| m.is_a?(Symbol) } or
+        fail ArgumentError, 'Mandatory arguments should be send as array of symbols'
+      @mandatory = mandatory
+      @optional = optional
+    end
+
+    def call(**params)
+      guard_missing!(params)
+      guard_unknown!(params)
+      params.merge(@optional.reject { |key,| params.key?(key) })
+    end
+
+    private
+
+    def guard_missing!(**params)
+      (@mandatory - params.keys).tap do |missing|
+        missing.empty? or fail ArgumentError, "missing keywords: #{missing.join(', ')}"
+      end
+    end
+
+    def guard_unknown!(**params)
+      (params.keys - @mandatory - @optional.keys).tap do |unknown|
+        unknown.empty? or fail ArgumentError, "unknown keywords: #{unknown.join(', ')}"
+      end
+    end
+  end
+end

data/lib/sho/configurator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Sho
+  # rubocop:disable Lint/UnderscorePrefixedVariableName
+
+  # Main Sho object providing rendering method creation API.
+  #
+  # There are three ways to create rendering methods:
+  #
+  # * {#template}: template is looked up relative to main folder, or {#base_folder};
+  # * {#template_relative}: template is looked up relative to current class' folder;
+  # * {#inline_template}: template is provided inline as a Ruby string/heredoc.
+  #
+  # @example
+  #   class AnyClass
+  #     include Sho
+  #
+  #     # `sho` returns an instance of Configurator
+  #     sho.template :rendering_method_name, 'path/to/template.slim', :param1, param2: default_value
+  #   end
+  #
+  class Configurator
+    # @private
+    attr_reader :host
+
+    # @return [String, nil] folder to look templates at for {#template} method. `nil` by default,
+    #   meaning application's current folder (`Dir.pwd`).
+    attr_accessor :base_folder
+
+    # @private
+    def initialize(host)
+      @host = host
+    end
+
+    # Generates instance method named `name` in a host module, which renders template from
+    # `template`.
+    # Instance of the host class is passed as a template scope on rendering.
+    #
+    # Template is looked up relative to application's main folder, or {#base_folder}.
+    #
+    # @example
+    #   # generates method with signature #profile()
+    #   sho.template :profile, 'app/views/users/profile.slim'
+    #
+    #   # generates method with signature #profile(context:, detailed: false)
+    #   # `context` and `detailed` vairables are accessible inside template.
+    #   sho.template :profile, 'app/views/users/profile.slim', :context, detailed: false
+    #
+    # @param name [Symbol] name of method to generate;
+    # @param template [String] path to template to render;
+    # @param _layout [Symbol, nil] name of method which provides layout (wraps results of current
+    #   method);
+    # @param mandatory [Array<Symbol>] list of mandatory params;
+    # @param optional [Hash{Symbol => Object}] list of optional params and their default values
+    def template(name, template, *mandatory, _layout: nil, **optional)
+      tpl = Tilt.new(File.expand_path(template, base_folder || Dir.pwd))
+      define_template_method(name, tpl, mandatory, optional, _layout)
+    end
+
+    # Like {#template}, but looks up template relative to host module path. Allows to structure
+    # views like:
+    #
+    # ```
+    # app/
+    # +- view_models/
+    #    +- users.rb   # calls sho.template_relative :profile, 'users/profile.slim'
+    #    +- users/
+    #       +- profile.slim
+    # ```
+    #
+    # @param name [Symbol] name of method to generate;
+    # @param template [String] path to template to render;
+    # @param _layout [Symbol, nil] name of method which provides layout (wraps results of current
+    #   method);
+    # @param mandatory [Array<Symbol>] list of mandatory params;
+    # @param optional [Hash{Symbol => Object}] list of optional params and their default values
+    def template_relative(name, template, *mandatory, _layout: nil, **optional)
+      base = File.dirname(caller(1..1).first.split(':').first)
+      tpl = Tilt.new(File.expand_path(template, base))
+
+      define_template_method(name, tpl, mandatory, optional, _layout)
+    end
+
+    # Inline rendering method definition, useful in decorators and other contexts with small
+    # templates.
+    #
+    # @example
+    #    sho.inline_template :badge,
+    #      slim: <<~SLIM
+    #        span.badge
+    #          span.name = user.name
+    #          i.role(class: user.role)
+    #      SLIM
+    #
+    # @param name [Symbol] name of method to generate;
+    # @param _layout [Symbol, nil] name of method which provides layout (wraps results of current
+    #   method);
+    # @param mandatory [Array<Symbol>] list of mandatory params;
+    # @param options [Hash{Symbol => Object}] list of optional params and their default values +
+    #   template to render (passed in a key named `slim:` or `erb:` or `haml:`, and so on).
+    def template_inline(name, *mandatory, _layout: nil, **options)
+      kind, template = options.detect { |key,| Tilt.registered?(key.to_s) }
+      template or fail ArgumentError, "No known templates found in #{options.keys}"
+      optional = options.reject { |key,| key == kind }
+      tpl = Tilt.default_mapping[kind].new { template }
+
+      define_template_method(name, tpl, mandatory, optional, _layout)
+    end
+
+    alias inline_template template_inline
+
+    private
+
+    def define_template_method(name, tilt, mandatory, optional, layout)
+      arguments = ArgumentValidator.new(*mandatory, **optional)
+      @host.__send__(:define_method, name) do |**locals|
+        locals = arguments.call(**locals)
+        if layout
+          __send__(layout) { tilt.render(self, **locals) }
+        else
+          tilt.render(self, **locals)
+        end
+      end
+    end
+  end
+  # rubocop:enable Lint/UnderscorePrefixedVariableName
+end

data/lib/sho/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Sho
+  MAJOR = 0
+  MINOR = 0
+  PATCH = 1
+  PRE = nil
+  VERSION = [MAJOR, MINOR, PATCH, PRE].compact.join('.')
+end

data/lib/sho.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'tilt'
+
+# Sho is a small, non-framework view library based on Tilt.
+#
+# `sho` object in an example below is an instance of {Sho::Configurator}, look at its docs to
+# understand how to define rendering methods.
+#
+# @example
+#   class AnyClass
+#     include Sho
+#
+#     sho.template :rendering_method_name, 'path/to/template.slim', :param1, param2: default_value
+#   end
+#
+#   # with instance of AnyClass:
+#   object.rendering_method_name(param1: 'foo', param2: 'bar') # => template.slim rendered
+#
+module Sho
+  # Adds `#sho` method (access to instance of {Sho::Configurator}) to class/module `Sho` is
+  # included into.
+  def self.included(mod)
+    mod.define_singleton_method(:sho) {
+      @__sho_configurator__ ||= Configurator.new(mod)
+    }
+  end
+end
+
+require_relative 'sho/argument_validator'
+require_relative 'sho/configurator'

metadata

@@ -0,0 +1,246 @@
+--- !ruby/object:Gem::Specification
+name: sho
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-06-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-junk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: saharspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: slim
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      Post-framework Ruby view library. It is based on Tilt and meant to provide entire
+      view layer for a web application (based on any framework or completely frameworkless).
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sho.rb
+- lib/sho/argument_validator.rb
+- lib/sho/configurator.rb
+- lib/sho/version.rb
+homepage: https://github.com/zverok/sho
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Experimental post-framework view library
+test_files: []