drawght 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a5dd8e8d4c11181d223311d1db2e25d8d6a9e7065289fb2ab40de86ce4fd054
-  data.tar.gz: c9698b4604f71e915915bc57ceefd595a21e36fa1969ea0d40e0f6fb907dbed9
+  metadata.gz: 9ed4619bbd991ccf58bd7e7c89407879181c656e98667b933a25cdf751a9c273
+  data.tar.gz: ae541e430afcc2ee112cd78d0549767845fbb1a8def0204de1d29e4db14baef9
 SHA512:
-  metadata.gz: f0e6771bf26dbacaf3d3c62dbfa947e87beb639cdad189b3c068227940a1c6410a25de09a6632b450f3128d924f9a32e90ec99910dc5e1fec803abc93f016801
-  data.tar.gz: 201f2fb4ad4de65f40d79f50d97da5244d826a18718e4bec2c84ee3935247fc0f0be49e34cc98a1d7867bb418afc90650c8b3e2aa38442684ff29460265d2b53
+  metadata.gz: 704e351d12da61369698dd568740d3943ee9542ac01c3d5e52c9bad514063ea6e1d395ba503df518a91605d44fb1bb7df0b68893527fa036ea74132d6680cafa
+  data.tar.gz: e10c78a814d001c3c7baa5eec7b748c5e34256b4a1dc7206d109372ec815279ba658f2ed1017838e7e233bf62befbe847b9df1af9fa4a4bc7b74090c9651b40a

data/CHANGELOG.yaml

@@ -1,3 +1,12 @@
+- version: 1.1.0
+  date: 2025-12-22
+  summary:
+    Syntax validation and new expression.
+  changes:
+  - Syntax validation.
+  - Refined extension methods have been moved to their respective modules.
+  - Syntax for getting the length of a collection.
+
 - version: 1.0.0
   date: 2025-12-03
   summary:

data/README.md

@@ -1,8 +1,8 @@
 # Drawght
 
-Drawght is a data handler for texts without logical statements. The goal is
-to use a dataset (such as the subject of a text) to draft a document
-template. It can be considered a mini template processor.
+Drawght (like draft/draught) is a data handler for texts without logical
+statements. The goal is to use a dataset (such as the subject of a text) to
+draft a document template. It can be considered a mini template processor.
 
 Data is accessed through `{}` braces, replaced by their respective values.
 
@@ -196,22 +196,63 @@ puts result
 
 Drawght has a simple syntax:
 
-- `{key}`: converts `key` to its respective value. If the value is a
-  collection, then the row will be replicated and converted with the respective
-  values. 
+- `{identifier}`: converts `identifier` to its respective value. If the value
+  is a collection, then the row will be replicated and converted with the
+  respective values.
 
-- `{object.key}`: converts `key` to its respective value inside `object`,
-  assuming the same behavior as `{key}`. 
+- `{structure.attribute}`: converts `attribute` to its respective value inside
+  `structure`, assuming the same behavior as `{identifier}`.
 
-- `{collection:key}`: selects `collection`, replicates the line for each item
-  in the collection, and converts `key` to its respective value contained in an
-  object within `collection`. The `collection` key can also be accessed by
-  `object.collection`, just as `key` can also be accessed by `object.key` which
-  will be converted following the same process in case it is a collection. 
+- `{collection:attribute}`: selects `collection`, replicates the line for each
+  item in the collection, and converts `attribute` to its respective value
+  contained in an structure within `collection`. The `collection` key can also
+  be accessed by `structure.collection`, just as `attribute` can also be
+  accessed by `structure.attribute` which will be converted following the same
+  process in case it is a collection.
 
-- `{collection#n.key}`: selects item object `n` (from 1) from `collection` and
-  converts `key` to its respective value. The whole process is similar to
-  `object.key`. 
+- `{collection#nth.attribute}`: selects the `nth` (start from 1) item from
+  `collection` and converts `attribute` to its respective value. The whole
+  process is similar to `structure.attribute`.
+
+- `{collection#$.attribute}`: selects the `nth` (start from 1) item from
+  `collection` and converts `attribute` to its respective value. The whole
+  process is similar to `structure.attribute`.
+
+### EBNF
+
+```ebnf
+identifier ::= initial_name { compound_name | space compound_name } ;
+
+initial_name ::= letter | "_" ;
+
+compound_name ::= letter | digit | "_" | "-" ;
+
+letter ::= "A"…"Z" | "a"…"z" ;
+
+digit ::= "0"…"9" ;
+
+space ::= " " ;
+
+expression ::= path [ length ] ;
+
+path ::= [ structural_path ] { sequential_path } ;
+
+structural_path ::= attribute { "." attribute } ;
+
+scoped_path ::= ":" structural_path ;
+
+attribute ::= element | item ;
+
+element ::= identifier [ index ] ;
+
+item ::= index ;
+
+index ::= "#" ( number | "$" ) ;
+
+number ::= digit { digit } ;
+
+length ::= "#&" ;
+```
 
 ## How it works
 

data/lib/drawght/compiler.rb

@@ -3,10 +3,31 @@
 
 module Drawght
 
+module HashExtensions
+  refine Hash do
+    def deep_stringify_keys!
+      transform_keys! do |key|
+        case value = fetch(key)
+        when Hash then value.deep_stringify_keys!
+        when Array then
+          value.map! do |item|
+            (item.is_a? Hash) ? item.deep_stringify_keys! : item
+          end
+        end
+
+        key.to_s
+      end
+
+      self
+    end
+  end
+end
+
 class Compiler
-  using Extensions
+  using HashExtensions
 
   include Parser
+  include Tracker
 
   attr_reader :template, :dataset, :result
 
@@ -30,11 +51,11 @@ class Compiler
 
   def convert
     lines = template.lines.map do |line|
-      next line unless line.match? PLACEHOLDERS_PATTERN
+      next line unless has_placeholders? line
 
       mapping_placeholders_from line
 
-      newline = convert_straightly_placeholders_from line
+      newline = convert_structural_placeholders_from line
 
       convert_sequential_placeholders_from newline
     end
@@ -42,12 +63,12 @@ class Compiler
     result.replace lines.join
   end
 
-  def convert_straightly_placeholders_from string
-    straightly_placeholders.reduce string.dup do |template, holding|
-      matter = dataset.ditch *pathkeys_from(holding)
+  def convert_structural_placeholders_from string
+    structural_placeholders.reduce string.dup do |template, expression|
+      matter = pathing dataset, *pathkeys_from(expression)
 
       converted = [matter].flatten.map do |value|
-        template.dup.gsub! holding.to_placeholder, value.to_s
+        template.dup.gsub! pathize(expression), value.to_s
       end
 
       template.replace converted.join
@@ -56,12 +77,12 @@ class Compiler
 
   def convert_sequential_placeholders_from string
     sequential_placeholders.reduce string.dup do |template, (attribute, mappings)|
-      matter = dataset.ditch *pathkeys_from(attribute)
+      matter = pathing dataset, *pathkeys_from(attribute)
 
       converted = matter.map do |values|
-        mappings.inject template.dup do |partial, (holding, key)|
-          value = values.ditch(*pathkeys_from(key)) || key
-          partial.dup.gsub! holding.to_placeholder, value.to_s
+        mappings.inject template.dup do |partial, (expression, key)|
+          value = pathing(values, *pathkeys_from(key)) || key
+          partial.dup.gsub! pathize(expression), value.to_s
         end
       end
 

data/lib/drawght/parser.rb

@@ -2,22 +2,126 @@
 # frozen_string_literal: true
 
 module Drawght
+  module ArrayExtensions
+    refine Array do
+      def add_unique item
+        push item unless include? item
+        self
+      end
+    end
+  end
+
   module Parser
-    using Extensions
-
-    def pathkeys_from placeholder
-      path = case placeholder
-             when ATTRIBUTES_PATTERN then
-               path_keys_for_attribute placeholder
-             when QUERY_PATTERN then
-               path_keys_for_query placeholder
-             else
-               [placeholder]
-             end
+    using ArrayExtensions
+
+    TOKENS = [
+      PREFIX = '{',
+      SUFFIX = '}',
+      ACCESSOR = '.',
+      INDEX = '#',
+      SCOPE = ':',
+      CONTEXT = '@',
+      LAST = '$',
+      LENGTH = '&',
+    ]
+
+    # Identifiers/name matches:
+    #
+    # - "name"
+    # - "variable name"
+    # - "variable-name"
+    # - "variable_name"
+    # - "_name_"
+    # - "name_"
+    # - "_name"
+    IDENTIFIER_MATCHES = "[A-Za-z_][A-Za-z0-9_\\-]*(?: [A-Za-z0-9_\\-]+)*"
+
+    # Index/item matches:
+    #
+    # - "#1" for first item.
+    # - "#n" for n-th item.
+    # - "#$" for last item.
+    INDEX_MATCHES = "\\#{INDEX}(?:\\d+|\\#{LAST})"
+
+    # Element matches:
+    #
+    # - "items#1" for first named item.
+    # - "items#n" for n-th named item.
+    # - "items#$" for last named item.
+    #
+    # Matches with IDENTIFIER_MATCHES and INDEX_MATCHES.
+    ELEMENT_MATCHES = "#{IDENTIFIER_MATCHES}(?:#{INDEX_MATCHES})?"
+
+    # Attribute matches.
+    ATTRIBUTE_MATCHES = "\\#{ACCESSOR}(?:#{ELEMENT_MATCHES})"
+
+    # Validation
+    #
+    # Structural matches:
+    #
+    # - "struct.attribute" for attribute value from struct.
+    # - "struct.substruct.attribute" for attribute value of the substruct from
+    #   struct.
+    # - "struct.items#1" for first item value in items of the struct.
+    # - "struct.items#1.attribute" for attribute value of the first item in
+    #   items of the struct.
+    # - "#1.attribute" for attribute value of the first item.
+    # - "#1.struct.attribute" for attribute value of the struct from the first item.
+    # - "items#1.attribute" for attribute value of the first item in items.
+    # - "items#1.struct.attribute" for attribute value of the struct of the
+    #   first item in items.
+    # - "items#1.subitems#1" for subitem value of the first item in items.
+    # - "items#1.subitems#1.attribute" for attribute value of the subitem from
+    #   first item in items.
+    #
+    # Scoped matches:
+    #
+    # ":attribute"
+    # ":collection:attribute"
+    # "collection:attribute"
+    # "collection:subcollection:attribute"
+    # "items#1:attribute"
+    # "struct.collection:attribute"
+    # "items#1.collection:attribute"
+    # "items#1.subitems#1:attribute"
+    # "items#1.subitems#1.collection:attribute"
+    # "struct.collection:noitcelloc.tcurts:attribute"
+    VALIDATION_PATTERN = Regexp.new "^(?=.*[A-Za-z_\\#{INDEX}])(?:(?:#{ELEMENT_MATCHES}|#{INDEX_MATCHES})(?:#{ATTRIBUTE_MATCHES})*)?(?:\\#{SCOPE}(?:#{ELEMENT_MATCHES})(?:#{ATTRIBUTE_MATCHES})*)*(?:\\#{INDEX}\\#{LENGTH})?$"
+
+    PLACEHOLDERS_PATTERN = Regexp.new "\\#{PREFIX}([^\\#{SUFFIX}]+)\\#{SUFFIX}"
+    STRUCTURE_TOKEN_PATTERN = Regexp.new "(\\#{ACCESSOR}|\\#{INDEX}|\\#{LENGTH}$)"
+    SCOPE_TOKEN_PATTERN = Regexp.new "(\\#{SCOPE})"
+    SCOPE_PATH_PATTERN = Regexp.new "^(.*)#{SCOPE_TOKEN_PATTERN}(.*)$"
+
+    NUMBER_PATTERN = /^\d+/
+
+    using ArrayExtensions
+
+    class SyntaxError < StandardError
+      def initialize syntax
+        super "Invalid syntax for \"#{syntax}\""
+      end
+    end
+
+    def pathkeys_from string
+      raise SyntaxError.new string unless syntax_valid? string
+
+      path = case string
+        when STRUCTURE_TOKEN_PATTERN then
+          pathkeys_for_structure string
+        when SCOPE_TOKEN_PATTERN then
+          pathkeys_for_collection string
+        else
+          [string]
+      end
 
       path.flatten
     end
 
+    def syntax_valid? string
+      string.match? VALIDATION_PATTERN
+    end
+
     def placeholders_from string
       return [] unless string =~ PLACEHOLDERS_PATTERN
 
@@ -28,61 +132,70 @@ module Drawght
       clear_placeholder_mappings!
 
       placeholders_from(string).map do |placeholder|
-        if placeholder =~ QUERY_PATTERN
-          placeholder.scan %r/^(.*)#{QUERY}(.*)$/ do |pathkeys, attribute|
+        if placeholder =~ SCOPE_TOKEN_PATTERN
+          placeholder.scan SCOPE_PATH_PATTERN do |pathkeys, _delimiter, attribute|
             (sequential_placeholders[pathkeys] ||= {}).update placeholder => attribute
           end
         else
-          straightly_placeholders.add placeholder
+          structural_placeholders.add_unique placeholder
         end
 
         placeholder
       end
     end
 
-    def straightly_placeholders
-      @straightly_placeholders ||= []
+    def structural_placeholders
+      @structural_placeholders ||= []
     end
 
     def sequential_placeholders
       @sequential_placeholders ||= {}
     end
 
-    def replace_placeholders template, value
-      case value
-      when Hash
-        replace_placeholder_attributes_for template, value
-      when Array
-        replace_placeholder_collections_for template, value
-      else
-        replace_placeholder_variables_from template, value
-      end
+    def has_placeholders? string
+      string.match? PLACEHOLDERS_PATTERN
+    end
+
+    def pathize string
+      "#{PREFIX}#{string}#{SUFFIX}"
     end
 
     private
 
-    def path_keys_for_attribute placeholder
-      placeholder.split(ATTRIBUTES_PATTERN).map do |item|
-        if item.to_s =~ QUERY_PATTERN
-          path_keys_for_query item
-        else
-          item.to_s =~ /^\d/ ? item.to_i - 1 : item unless item.to_s.empty?
-        end
-      end.compact
+    def pathkeys_for_structure placeholder
+      placeholder
+        .split(STRUCTURE_TOKEN_PATTERN)
+        .reject{ |expression| [ACCESSOR, INDEX].include? expression }
+        .map do |expression|
+          value = zeroize expression
+
+          if value =~ SCOPE_TOKEN_PATTERN
+            pathkeys_for_collection expression
+          else
+            value =~ NUMBER_PATTERN ? value.to_i - 1 : expression unless value.empty?
+          end
+        end.compact
+    end
+
+    def zeroize value, token: LAST
+      value.to_s.sub token, '0'
     end
 
-    def path_keys_for_query placeholder
-      placeholder.gsub(QUERY, "#{QUERY}&#{QUERY}").split(QUERY_PATTERN).map do |item|
-        if item.to_s =~ ATTRIBUTES_PATTERN
-          path_keys_for_attribute item
+    def pathkeys_for_collection placeholder
+      placeholder.split(SCOPE_TOKEN_PATTERN).map do |expression|
+        case expression.to_s
+        when STRUCTURE_TOKEN_PATTERN then
+          pathkeys_for_structure expression
+        when SCOPE then
+          CONTEXT
         else
-          item
+          expression
         end
       end
     end
 
     def clear_placeholder_mappings!
-      straightly_placeholders.clear && sequential_placeholders.clear
+      structural_placeholders.clear && sequential_placeholders.clear
     end
   end
 end

data/lib/drawght/tracker.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module Drawght
+
+module Tracker
+  LENGTH = Parser::LENGTH
+  CONTEXT = Parser::CONTEXT
+
+  def pathing hash, *pathkeys
+    if i = pathkeys.index CONTEXT
+      prefixes, suffixes = pathkeys.slice(0..i - 1), pathkeys.slice(i + 1..-1)
+      result = pathing(hash, *prefixes).map{ |item| pathing item, *suffixes }
+      suffixes.last == LENGTH ? result.reduce(&:+) : result
+    elsif pathkeys.last == LENGTH
+      hash.dig(*pathkeys.slice(0..-2)).length
+    else
+      hash.dig *pathkeys
+    end
+  rescue => error
+    raise error, "The pathkeys \"#{pathkeys.join ' '}\" is a not valid path"
+  end
+end
+
+end # Drawght

data/lib/drawght/version.rb

@@ -1,12 +1,11 @@
 # encoding: utf-8
 
 module Drawght
-  VERSION = "1.0.0"
-  RELEASE_DATE = "2025-12-03"
+  VERSION = "1.1.0"
+  RELEASE_DATE = "2025-12-22"
   CHANGESET = [
-    "New compiler process.",
-    "Refined extension methods have been added.",
-    "Test coverage.",
-    "Syntax revision for nested values in collections.",
+    "Syntax validation.",
+    "Refined extension methods have been moved to their respective modules.",
+    "Syntax for getting the length of a collection.",
   ]
 end

data/lib/drawght.rb

@@ -2,69 +2,8 @@
 # frozen_string_literal: true
 
 module Drawght
-  TOKENS = [
-    PREFIX = '{',
-    SUFFIX = '}',
-    ATTRIBUTE = '.',
-    ITEM = '#',
-    QUERY = ':',
-  ]
-
-  PLACEHOLDERS_PATTERN = Regexp.new "\\#{PREFIX}([^\\#{SUFFIX}]+)\\#{SUFFIX}"
-
-  ATTRIBUTES_PATTERN = Regexp.new "\\#{ATTRIBUTE}|\\#{ITEM}"
-  ATTRIBUTE_PATTERN = Regexp.new "\\#{ATTRIBUTE}"
-  ITEM_PATTERN = Regexp.new "\\#{ITEM}"
-  QUERY_PATTERN = Regexp.new "\\#{QUERY}"
-
-  PATH_PATTERN = Regexp.new "\\#{ATTRIBUTE}|\\#{ITEM}|\\#{QUERY}"
-
-  module Extensions
-    refine Hash do
-      def deep_stringify_keys!
-        transform_keys! do |key|
-          case value = fetch(key)
-          when Hash then value.deep_stringify_keys!
-          when Array then
-            value.map! do |item|
-              (item.is_a? Hash) ? item.deep_stringify_keys! : item
-            end
-          end
-
-          key.to_s
-        end
-
-        self
-      end
-
-      def ditch *pathkeys
-        if i = pathkeys.index('&')
-          list, subpath = pathkeys[0..i - 1], pathkeys[i + 1..-1]
-          dig(*list).map{ |item| item.ditch *subpath }
-        else
-          dig *pathkeys
-        end
-      rescue => error
-        error.message += "The pathkeys \"#{pathkeys.join ','}\" is a not valid path"
-        raise error
-      end
-    end
-
-    refine Array do
-      def add item
-        push item unless include? item
-        self
-      end
-    end
-
-    refine String do
-      def to_placeholder
-        "#{PREFIX}#{self}#{SUFFIX}"
-      end
-    end
-  end
-
   require_relative "drawght/parser"
+  require_relative "drawght/tracker"
   require_relative "drawght/compiler"
   require_relative "drawght/version"
 

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: drawght
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Hallison Batista
 bindir: bin
 cert_chain: []
-date: 2025-12-03 00:00:00.000000000 Z
+date: 2025-12-22 00:00:00.000000000 Z
 dependencies: []
 description: |
-  Drawght v1.0.0 (2025-12-03)
+  Drawght v1.1.0 (2025-12-22)
 
   Drawght is a data handler for texts without logical statements. The goal is
   to use a dataset (such as the subject of a text) to draft a document
@@ -18,10 +18,9 @@ description: |
 
   Latest changes:
 
-  - New compiler process.
-  - Refined extension methods have been added.
-  - Test coverage.
-  - Syntax revision for nested values in collections.
+  - Syntax validation.
+  - Refined extension methods have been moved to their respective modules.
+  - Syntax for getting the length of a collection.
 email: email@hallison.dev.br
 executables: []
 extensions: []
@@ -34,6 +33,7 @@ files:
 - lib/drawght/compiler.rb
 - lib/drawght/mapper.rb
 - lib/drawght/parser.rb
+- lib/drawght/tracker.rb
 - lib/drawght/version.rb
 homepage: https://drawght.github.io
 licenses:
@@ -55,5 +55,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Drawght parser implementation in Ruby.
+summary: Drawght implementation in Ruby.
 test_files: []