bidify 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 869c99f4077d50f88ff976b15ab4106fd15900e45af1bd5673de5255b6cfb8ef
-  data.tar.gz: 688dfb1fcab1cbfb627a851951ca80a16479c96c6498b036f3a0e3453441b7f0
+  metadata.gz: 32b3c244317bd021ff911b1be914990a87e7056b64d7c7ef8ec08fe4597721d0
+  data.tar.gz: db60b88d64e4c288d7160072ffb67edebb46959941294159ab231593ee6d8217
 SHA512:
-  metadata.gz: 56b5b3058a06f7fe748796490cf53d940b81257bfa4e7990045d788170082a000c463a2fce8c85a9e1d63eb306d2ff471b95f5091fddd0ed49a2e328aaebd3cc
-  data.tar.gz: aa3cdec3d581149a8c57ee692d4bb912eb86adadddbad364ebda35acda25d6c0905eb329b79406adf187f486adef4077ac246c28b73aacbea4b1ac63922c4fdf
+  metadata.gz: 7ff62ccd19cef7e7427e7a369d97d3832325066e0c73f6ef6ef1fe1774d5895cc3212d82e9df3be6534e614249b0047056483ba4d78cd78bbb9b0648b8134804
+  data.tar.gz: 23389f67993355bd021f140b4392b4641800cb01fff36ae0b232a27c70d072c84103f791e83517510ee2c64db4f91765274f2dd4e804d42c10a063b640d81589

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bidify (0.1.0)
+    bidify (0.2.0)
       nokogiri (~> 1.14)
 
 GEM

data/README.md

@@ -2,7 +2,8 @@
 
 Bidify helps to add bidirectional text support to HTML documents.
 
-The project is in its very early stage of development and its interface or functionality may break from one version to another. Use it with caution.
+The project is in its very early stage of development, and its interface or
+functionality may break from one version to another. Use it with caution.
 
 ## Usage
 
@@ -10,10 +11,76 @@ The project is in its very early stage of development and its interface or funct
 require 'bidify'
 
 html_input = '<p>some content even in nested format</p>'
-bidified_html = Bidify.bidify(html_input)
+bidified_html = Bidify.bidify_html_string(html_input)
 # bidified_html: '<p dir="auto">some content even in nested format</p>' 
 ```
 
+## Rules
+
+Bidification (the `dir="auto"` attribute) follows these simple rules:
+
+- It applies to "bidifiable" tags.
+- It excludes the first immediate child element.
+- It excludes `li` tags.
+
+The default bidifiable tags are `div`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`,
+`p`, `ul`, `ol`, and `blockquote`. One can modify this list using options.
+
+As a complementary step, CSS styles should use [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). Here are a few examples:
+
+```css
+/* Physical properties */
+text-align: left;
+padding-right: 10px;
+border-left: 1px;
+/* Logical properties */
+text-align: start;
+padding-inline-end: 10px;
+border-inline-start: 1px;
+```
+
+## Configuration
+
+To use this gem with custom configuration, use the following syntax and pass
+options while creating an instance of bidifier:
+
+```rb
+options = {
+  # ...
+}
+
+bidifier = Bidify::HtmlStringBidifier.new(options)
+
+puts bidifier.apply('<div>input stringified html</div>')
+```
+
+### Options
+
+Available options with their default values are as follows:
+
+- `excluding_tags: []`
+
+    Removes tags from the list of bidifiable tags. This option affects the
+    provided tags in `including_tags` options.
+
+- `including_tags: []`
+
+    Adds new tags to the list of bidifiable tags
+
+- `greedy: false`
+
+    By default, bidification stops when it reaches an element that has `dir`
+    attribute. Use `true` to disregard any existing `dir` attributes.
+
+- `only_tags: []`
+
+    It sets the bidifiable tags to the given tags.
+
+- `with_table_support: false`
+
+    Use `true` to add table tags support.
+
 ## License
 
-This project is a Free/Libre and Open Source software released under LGPLv3 license.
+This project is a Free/Libre and Open Source software released under LGPLv3
+license.

data/lib/bidify/bidifier.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Bidify
+  # Super class for custom bidifiers
+  class Bidifier
+    ###
+    # Instanciate a bidifier object with the given optional options hash
+    #
+    # @param [Hash] options
+    #
+    def initialize(options = {})
+      @options = options
+
+      configure
+    end
+
+    def apply
+      raise NotImplementedError
+    end
+
+    private
+
+    def configure
+      @bidifiable_tags = DEFAULT_BIDIFIABLE_TAGS.dup
+      @bidifiable_tags.concat(TABLE_TAGS) if @options[:with_table_support]
+      @bidifiable_tags.concat(@options[:including_tags]) if @options.key?(:including_tags)
+      @bidifiable_tags.delete_if { |tag| @options[:excluding_tags]&.include?(tag) }
+      @bidifiable_tags = @options[:only_tags] if @options.key?(:only_tags)
+    end
+
+    def bidify_recursively(html_node, options = {})
+      seen_the_first_bidifiable_element = false
+
+      html_node.children.each do |child_node|
+        next if stop_recursion_at?(child_node)
+
+        bidify_recursively(child_node)
+
+        if (options[:root] || seen_the_first_bidifiable_element) && @bidifiable_tags.include?(child_node.name)
+          child_node.set_attribute('dir', 'auto')
+        end
+
+        seen_the_first_bidifiable_element = true if actual_content?(child_node)
+      end
+    end
+
+    def actual_content?(node)
+      node.element? || (node.text? && !node.blank?)
+    end
+
+    def stop_recursion_at?(node)
+      return false if @options[:greedy] == true
+
+      node.has_attribute?('dir')
+    end
+  end
+end

data/lib/bidify/html_string_bidifier.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require_relative 'bidifier'
+
+module Bidify
+  ###
+  # Bidifying html input as string
+  #
+  # == Example Usage
+  #
+  # Here's an example of how to use the class:
+  #
+  #   bidifier = HtmlStringBidifier.new
+  #   bidifier.apply("<p>text</p>")
+  #
+  class HtmlStringBidifier < Bidifier
+    ###
+    # Applies dir="auto" to the given html string with default configuration
+    #
+    # @param [String] html_string a stringified HTML content
+    # @return [String] Bidified version of the input string
+    #
+    def apply(html_input)
+      html_node = Nokogiri::HTML.fragment(html_input)
+      bidify_recursively(html_node, { root: true })
+
+      html_node.to_s
+    end
+  end
+end

data/lib/bidify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidify
-  VERSION = '0.1.1'
+  VERSION = '0.3.0'
 end

data/lib/bidify.rb

@@ -1,43 +1,27 @@
 # frozen_string_literal: true
 
-require 'nokogiri'
+require 'bidify/html_string_bidifier'
 
-# Bidify applies `dir="auto"` to the given html string
+# == Bidify module
 #
-# ### Example:
+# The namespace and helper methods for bidiying HTML contents
 #
-#    bidified_html = Bidify.bidify(regular_html)
+# == Example:
+#
+#    bidified_html = Bidify.bidify_html_string(regular_html)
 module Bidify
-  @bidifiable_tags = %w[div h1 h2 h3 h4 h5 h6 p ul ol blockquote]
+  DEFAULT_BIDIFIABLE_TAGS = %w[div h1 h2 h3 h4 h5 h6 p ul ol blockquote].freeze
+  TABLE_TAGS = %w[table thead tbody th tr td].freeze
 
   class << self
     ###
-    # bidify applies dir="auto" to the given html string
-    def bidify(input_html)
-      html_node = Nokogiri::HTML.fragment(input_html)
-      bidify_recursively(html_node, { root: true })
-
-      html_node.to_s
-    end
-
-    private
-
-    def bidify_recursively(html_node, options = {})
-      seen_the_first_bidifiable_element = false
-
-      html_node.children.each do |child_node|
-        bidify_recursively(child_node)
-
-        if (options[:root] || seen_the_first_bidifiable_element) && @bidifiable_tags.include?(child_node.name)
-          child_node.set_attribute('dir', 'auto')
-        end
-
-        seen_the_first_bidifiable_element = true if actual_content?(child_node)
-      end
-    end
-
-    def actual_content?(node)
-      node.element? || (node.text? && !node.blank?)
+    # Applies dir="auto" to the given html string with default configuration
+    #
+    # @param [String] html_string a stringified HTML content
+    # @return [String] Bidified version of the input string
+    #
+    def bidify_html_string(html_string)
+      Bidify::HtmlStringBidifier.new.apply(html_string)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bidify
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Mostafa Ahangarha
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-25 00:00:00.000000000 Z
+date: 2023-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -36,6 +36,8 @@ files:
 - LICENSE
 - README.md
 - lib/bidify.rb
+- lib/bidify/bidifier.rb
+- lib/bidify/html_string_bidifier.rb
 - lib/bidify/version.rb
 homepage: https://github.com/dobidi/bidify-rb
 licenses: