share_with 1.0.0

data/README.md

@@ -0,0 +1,54 @@
+# ShareWith
+
+This is a Ruby gem thought to render the sharing links for the most popular networks.
+
+*ShareWith* also introduces a syntax, built upon a YAML file, to declare parameters and templates, and
+elements to self-describe the service itself.
+
+This YAML file will be used to generate the object that renders the templates in plain HTML text.
+
+[![Ruby](https://github.com/fabiomux/share_with/actions/workflows/main.yml/badge.svg)][wf_main]
+[![Gem Version](https://badge.fury.io/rb/share_with.svg)][gem_version]
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add share_with
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install share_with
+
+## Usage
+
+As first step must *require* the gem:
+```ruby
+require "share_with"
+```
+
+Then we can instantiate the *Collection* class and the list of services to load: 
+```ruby
+@collection = ShareWith::Collection.new(services: ["twitter", "facebook"])
+```
+
+Once filled the *params* required to render the template:
+```ruby
+@collection.set_value_to_all("url", "https://freeaptitude.altervista.org/projects/share-with.html")
+```
+
+Finally we get the HTML code as a text string:
+```ruby
+@collection.render_all("icon")
+```
+
+## More Help
+
+More info is available at:
+- the [project page on the Freeaptitude blog][project_page];
+- the [ShareWith Github wiki][share_with_wiki].
+
+[project_page]: https://freeaptitude.altervista.org/projects/share-with.html "Project page on the Freeaptitude blog"
+[share_with_wiki]: https://github.com/fabiomux/share_with/wiki "ShareWith wiki page on GitHub"
+[wf_main]: https://github.com/fabiomux/share_with/actions/workflows/main.yml
+[gem_version]: https://badge.fury.io/rb/share_with

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/share_with/collection.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ShareWith
+  #
+  # Entry point class that handles the service collection.
+  #
+  class Collection
+    attr_reader :services
+
+    def initialize(args = {})
+      @paths = args[:paths] || []
+      @extend_with = args[:extend_with] || []
+      @services = {}
+      return unless args[:services]
+
+      args[:services].each do |s|
+        @services[s.to_sym] = Service.new(s, { paths: @paths, extend_with: @extend_with })
+      end
+    end
+
+    def inspect(service, var_path)
+      @services[service.to_sym].inspect(var_path)
+    end
+
+    def param(service, key)
+      @services[service.to_sym].get_param(key) if @services.key?(service.to_sym)
+    end
+
+    def params_list(service)
+      @services[service.to_sym].params_list if @services.key?(service.to_sym)
+    end
+
+    def params_lists
+      res = []
+      services.each do |s|
+        res.push(*params_list(s))
+      end
+      res.uniq
+    end
+
+    def set_param(service, key, value)
+      @services[service.to_sym].set_param(key, value) if @services.key?(service.to_sym)
+    end
+
+    def set_param_to(services, key, value)
+      services.each do |s|
+        set_param s, key, value if @services.key? s.to_sym
+      end
+    end
+
+    def set_param_to_all(key, value)
+      @services.each_key do |s|
+        set_param(s, key, value)
+      end
+    end
+
+    def set_conditional_param(key, value)
+      if key.include? ":"
+        services, param = key.split(":")
+        set_param_to(services.split(","), param, value)
+      else
+        set_param_to_all(key, value)
+      end
+    end
+
+    def get_value(service, key)
+      @services[service.to_sym].get_value(key)
+    end
+
+    def set_value(service, key, value)
+      @services[service.to_sym].set_value(key, value)
+    end
+
+    def set_value_to(services, key, value)
+      services.each do |s|
+        set_value s, key, value if @services.key? s.to_sym
+      end
+    end
+
+    def set_value_to_all(key, value)
+      @services.each_key do |s|
+        set_value(s, key, value)
+      end
+    end
+
+    def create_or_reset(service)
+      if @services.include? service.to_sym
+        @services[service.to_sym].reset!
+      else
+        @services[service.to_sym] = Service.new(service, { paths: @paths, extend_with: @extend_with })
+      end
+    end
+
+    def reset_all!
+      @services.each do |_k, s|
+        s.reset!
+      end
+    end
+
+    def render(service, template)
+      @services[service.to_sym].render(template)
+    end
+
+    def render_all(template)
+      res = {}
+      @services.each do |k, _v|
+        res[k] = render(k, template)
+      end
+
+      res
+    end
+  end
+end

data/lib/share_with/link_factory.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ShareWith
+  #
+  # Methods to create the HTML code to represent the sharing links.
+  #
+  module LinkFactory
+    def render(tpl_name)
+      raise InvalidTemplate, tpl_name unless templates.key? tpl_name.to_sym
+
+      template = templates[tpl_name.to_sym]
+
+      merge_template!(template[:inherit_from], tpl_name) if template.key? :inherit_from
+
+      includes&.each do |k, _v|
+        i = includes[k]
+        i[:cache] = traverse_node(i[:content]) unless i.key? :cache
+      end
+
+      traverse_node(template[:content])
+    end
+
+    private
+
+    def traverse_node(node)
+      res = []
+
+      if node.instance_of? Hash
+        node.each do |k, v|
+          attr = ""
+          attr = expand_attributes(v) if v.key? :attr
+          res << (v.key?(:content) ? "<#{k} #{attr}>#{traverse_node(v[:content])}</#{k}>" : "<#{k} #{attr} />")
+        end
+      elsif node.instance_of? String
+        res << expand_all(node)
+      end
+
+      res.join
+    end
+
+    def expand_attributes(value)
+      value[:attr].keys.map do |k|
+        if value[:attr][k].nil?
+          str = k
+        else
+          str = expand_all(value[:attr][k])
+          str = "#{k}=\"#{str}\"" unless str.empty?
+        end
+        str
+      end.delete_if(&:empty?).join " "
+    end
+  end
+end

data/lib/share_with/placeholders.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ShareWith
+  #
+  # It provides the methods to replace the placeholders
+  #   with the correct data pointed.
+  #
+  module Placeholders
+    def expand_all(str)
+      loop do
+        # Conditional params, if null remove the string
+        str = str.gsub(/\[([^ \]]+)\]/) do |x|
+          res = expand_all(x.delete("[]"))
+          @empty ? "" : res
+        end
+
+        str = str.gsub(%r{<([^ />]+)>}) do |x|
+          res = inspect(x.delete("<>"))
+          @empty = res.to_s.empty?
+          res.nil? ? x : res
+        end
+
+        break unless str =~ %r{<[^ />]+>}
+      end
+
+      str
+    end
+
+    def inspect(var_path)
+      context, var_name, var_select, attr_key = var_path.split(".")
+      var_select ||= :value
+      # puts @data,var_name,var_select if context.to_sym == :https
+      res = send(context.to_sym)
+
+      raise InvalidContext, context if res.nil?
+
+      return res.send(var_name.to_sym) if %i[keys values].include? var_name.to_sym
+
+      raise InvalidParam, [context, var_name].join(".") unless res.key? var_name.to_sym
+
+      res = res[var_name.to_sym]
+      case context.to_sym
+      when :params
+        value_selection(res, attr_key, var_select)
+      when :includes
+        res[:cache]
+      else
+        res
+      end
+    end
+
+    private
+
+    def value_selection(val, attr_key, var_select)
+      case var_select.to_s.to_sym
+      when :key
+        val.key
+      when :attr
+        val.attr(attr_key)
+      else
+        val.value
+      end
+    end
+  end
+end

data/lib/share_with/service.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ShareWith
+  #
+  # The single service classification.
+  #
+  class Service
+    include Placeholders
+    include LinkFactory
+
+    def initialize(service_name, args = {})
+      @name = service_name
+      @paths = [].concat args[:paths].to_a
+      @extend_with = args[:extend_with] || []
+      @paths << File.join(File.dirname(__FILE__), "services")
+      @data = load(@name)
+
+      @data = inherit_from(info[:inherit_from]) if info.key?(:inherit_from)
+
+      @extend_with = (info[:extend_with] || []).concat(@extend_with) if info.key?(:extend_with)
+
+      # if info.key?(:extend_with)
+      if @extend_with
+        # extend_with_layers(info[:extend_with])
+        extend_with_layers(@extend_with)
+      else
+        # Create the params when no more extensions are requested.
+        create_params
+      end
+    end
+
+    def param?(key)
+      params.key?(key.to_sym)
+    end
+
+    def params_list
+      params.keys
+    end
+
+    def get_param(key)
+      return params[key.to_sym].value if param?(key)
+    end
+
+    def set_param(key, value)
+      params[key.to_sym].value = value if param?(key)
+    end
+
+    def set_conditional_param(key, value)
+      if key.include? ":"
+        services, param = key.split(":")
+        set_param(param, value) if services.split(",").include?(@name)
+      else
+        set_param(key, value)
+      end
+    end
+
+    def get_value(key)
+      raise InvalidParam, "params.#{key}" unless param?(key.to_sym)
+
+      params[key.to_sym].value
+    end
+
+    def set_value(key, value)
+      raise InvalidParam, "params.#{key}" unless param?(key.to_sym)
+
+      params[key.to_sym].value = value
+    end
+
+    def reset!
+      params.each { |_k, v| v.reset! }
+      includes.each { |_k, v| v.delete :cache }
+      # extend_with_layers(@extend_with)
+    end
+
+    def add_layer(layer)
+      @extend_with << layer
+      extend_with_layers(layer)
+    end
+
+    private
+
+    def info
+      @data[:info]
+    end
+
+    def templates
+      @data[:templates]
+    end
+
+    def params
+      @data[:params]
+    end
+
+    def includes
+      @data[:includes]
+    end
+
+    def create_params
+      params.each do |k, v|
+        @data[:params][k] = ServiceDataFactory.create(v) if [String, Hash].include? v.class
+      end
+    end
+
+    def extend_with_layers(layers)
+      layers = [layers] if layers.instance_of? String
+      layers.each do |name|
+        name = name.split(".")
+        layer = load("_#{name[0]}")[name[1]]
+
+        raise InvalidLayer, [name[0], name[1]] if layer.nil?
+
+        @data[:params].merge!(layer[:params]) if layer.key? :params
+        @data[:includes].merge!(layer[:includes]) if layer.key? :includes
+        @data[:templates].merge!(layer[:templates]) if layer.key? :templates
+      end
+
+      create_params
+    end
+
+    def inherit_from(service_name)
+      data = load(service_name)
+      data[:info] = {}.merge! @data[:info]
+      data[:params].merge!(params) unless params.empty?
+      data[:includes].merge!(includes) unless includes.empty?
+      data[:templates].merge!(templates) unless templates.empty?
+
+      data
+    end
+
+    def merge_template!(service_name, tpl_name)
+      source = load(service_name)
+      @data[:includes].merge! source[:includes]
+      @data[:templates][tpl_name.to_sym].merge! source[:templates][tpl_name.to_sym]
+      # to don't merge again and again
+      @data[:templates][tpl_name.to_sym].delete :inherit_from
+    end
+
+    def load(service_name)
+      @paths.each do |d|
+        fname = File.join(File.expand_path(d), "#{service_name}.yaml")
+        next unless File.exist? fname
+
+        res = YAML.load_file(fname)
+        res[:includes] ||= {}
+        res[:params] ||= {}
+        res[:templates] ||= {}
+        return res
+      end
+      raise InvalidService, service_name
+    end
+  end
+end

data/lib/share_with/service_data.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module ShareWith
+  #
+  # Define the data type allowed.
+  #
+  module ServiceDataType
+    #
+    # This works as an abstract class to inherit.
+    #
+    class BasicDataType
+      attr_reader :label
+      attr_writer :value
+
+      def initialize(data)
+        @data = data
+        @default = data[:default]
+        @value = @default
+      end
+
+      def value(encoding = nil)
+        res = @value || @default || ""
+        res = res.send(encoding.to_sym) unless encoding.nil?
+
+        res
+      end
+
+      def attr(attr_value)
+        @data[:attr][attr_value]
+      end
+
+      def reset!
+        self.value = @default
+      end
+    end
+
+    #
+    # Define a boolean type.
+    #
+    class Boolean < BasicDataType
+      def value=(val)
+        @value = [true, "true", 1, "1"].include? val
+      end
+    end
+
+    #
+    # Define an integer type.
+    #
+    class Integer < BasicDataType
+      def value=(val)
+        @value = val.to_i
+      end
+    end
+
+    #
+    # Define a list of string type.
+    #
+    class StringList < BasicDataType
+      def initialize(data)
+        super
+        @value = []
+        @separator = data[:separator] || ","
+        reset!
+      end
+
+      def value
+        @value.to_text_list @separator
+      end
+
+      def value=(val)
+        val = val.split(@separator) if val.instance_of?(String)
+        val = "" if val.nil?
+
+        if val.empty?
+          clear
+        else
+          @value.concat val
+        end
+      end
+
+      def delete(val)
+        @value.delete val
+      end
+
+      def clear
+        @value.clear
+      end
+
+      def reset!
+        clear
+        @value = @default.instance_of?(String) ? @default.split(@separator).map(&:trim) : @default.clone
+      end
+    end
+
+    #
+    # Define a select value type.
+    #
+    class Select < BasicDataType
+      # aliasing the ancestor method to meet the new meanings
+      alias key value
+
+      def value
+        @data[:options][key].instance_of?(String) ? @data[:options][key] : @data[:options][key][:value]
+      end
+
+      def value=(val)
+        raise InvalidValue, [val, @data[:options].keys] unless @data[:options].key? val
+
+        @value = val
+      end
+
+      def attr(attr_value)
+        @data[:options][key][:attr][attr_value]
+      end
+    end
+
+    #
+    # Define an encoded text type.
+    #
+    class EncodedText < BasicDataType
+      def value
+        super :to_escaped_html
+      end
+    end
+
+    #
+    # Define a plain text type.
+    #
+    class PlainText < BasicDataType
+      def value
+        super :to_plain_text
+      end
+    end
+
+    #
+    # Define an encoded URL type.
+    #
+    class EncodedUrlParam < BasicDataType
+      def value
+        super :to_encoded_url_param
+      end
+    end
+
+    #
+    # Define a reference type.
+    #
+    class Reference < BasicDataType
+      def initialize(data)
+        super type: :reference, default: data
+      end
+
+      def value=(val)
+        # No value can be assigned being only a reference
+      end
+
+      def value
+        "<#{@value.gsub(/[^a-z._]+/, "")}>"
+      end
+    end
+  end
+
+  #
+  # Convert an argument to a ServiceDataType object.
+  #
+  class ServiceDataFactory
+    def self.create(args)
+      if args.instance_of? String
+        res = ServiceDataType::Reference.new(args)
+      else
+        type = args[:type].to_s.split("_").map(&:capitalize).join
+        raise InvalidDataType, type unless ShareWith::ServiceDataType.constants.include? type.to_sym
+
+        res = Object.const_get("ShareWith::ServiceDataType::#{type}").new(args)
+      end
+
+      res
+    end
+  end
+end

data/lib/share_with/services/_base.yaml

@@ -0,0 +1,77 @@
+---
+:info:
+  :name: 'Service Name'
+  :classname: 'service-name'
+  :home_page: 'https://...'
+  :language_area: :general
+  :link: 'https://sharing-url.com/plus/path/and/tags?url=<params.url>&title=<params.title>[&nullable=<params.null>]'
+  :description: 'Service description used only as documentation'
+
+:params:
+  :icon: '<params.icon_size.value>'
+  :icon_size:
+    :type: :select
+    :default: 'large'
+    :options:
+      small:
+        :value: 'https://cdn...'
+        :label: 'Small'
+        :attr:
+          url: ''
+          width: 20
+          height: 20
+      medium:
+        :value: '...'
+        :label: 'Medium'
+        :attr:
+          width: 30
+          height: 30
+      large:
+        :value: '...'
+        :label: 'Large'
+        :attr:
+          width: 48
+          height: 48
+  :icon_width: '<params.icon_size.attr.width>'
+  :icon_height: '<params.icon_size.attr.height>'
+  :title:
+    :default: ''
+    :type: :encoded_url_param
+  :url:
+    :default: ''
+    :type: :encoded_url_param
+
+:includes:
+  :service_icon:
+    :content:
+      img:
+        :attr:
+          src: '<params.icon>'
+          alt: 'Share with <info.name>'
+          width: '<params.icon_width>'
+          height: '<params.icon_height>'
+:templates:
+  :icon:
+    :content:
+      a:
+        :attr:
+          href: '<info.link>'
+          title: 'Share with <info.name>'
+          class: 'share-with-<info.classname>'
+        :content: '<includes.service_icon>'
+  :icon_and_text:
+    :content:
+      a:
+        :attr:
+          href: '<info.link>'
+          title: 'Share with <info.name>'
+          class: 'share-with-<info.classname>'
+        :content: '<includes.service_icon> <info.name>'
+  :text:
+    :content:
+      a:
+        :attr:
+          href: '<info.link>'
+          title: 'Share with <info.name>'
+          class: 'share-with-<info.classname>'
+        :content: '<info.name>'