nested_array 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b49067e4c7566810e2689fd293994ae2f8c8b5cb40dfab84e7eb73f440dccd6
-  data.tar.gz: 3cf05731a72c97d59486f916ac89ce33c3d8c32cd6775e14ceefad498ee11022
+  metadata.gz: 1cbdc891f87c006049f2995ac7d0337e6b0c36b3fd18eb9e71ff57725c1b3302
+  data.tar.gz: 07ab1ff64ded9400e418042fe8159c82e46db8603947f4da77eaa49a50b16752
 SHA512:
-  metadata.gz: c79be9c3ad75d6ee6c6d170fdc7116587e3bd0f0924e8a904ca74f2abb0486c9e748325e66173c1055622106ea6e10a20bd107f6e7e4c56398210d867afa46eb
-  data.tar.gz: ef2dc1b64710fe0a647f6fd81f0e05cd26ad68abda8a76fb6e4f27c05ccf3be38ca4e5d69bd2d241d692505e619f942df894601dbebdf8b4324ab4e2de7e901f
+  metadata.gz: f0cd5151f188b7323a42cddbfd114a645b6677df026933c2254e446022d04206c45d9042d3ae3d8fcada6a76efe00b2ec4184c86c8a9a6d6c2d08f2aed98b731
+  data.tar.gz: 49b10c6de7ab78ce83ab61e75653a9564dc9359060f3acf4c7bed9512c916302b0b6a4766516a0890144d373b1fac1207ad4bfce2c870f8c35cd21f76d492d95

data/.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/.rspec

@@ -1 +1,4 @@
---require spec_helper
+--color # Вывод в цвете
+--require spec_helper # Подключить файл по умолчанию
+--order rand # В случайном порядке
+--format doc # Вывод в формате

data/.rubocop.yml

@@ -0,0 +1,125 @@
+# Игнорировать отсутствие магического комментария:
+# frozen_string_literal: true
+# 
+# Надо понимать что мы теряем производительность если не используем замороженные
+# строки там где это возможно, применяйте!: ` -"неизменяемая строка" `
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Надо понимать что есть качественное различие между
+# 
+# module Foo
+#   class Bar
+#   end
+# end
+# 
+# и
+# 
+# class Foo::Bar
+# end
+# 
+# Если где то в модуль вынесен код:
+# 
+# module Foo
+#   X = 42
+# end
+# 
+# то следует инициализировать модуль До класса-потомка, иначе ошибка. Как выход,
+# рубокоп предлагает везде использовать первый синтаксис, а это некрасиво)
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Корячить пустые методы с точка-запятой, нет уж извините!
+Style/EmptyMethod:
+  Enabled: false
+
+# Не даёт сравнимать с нуль (... == 0), заставляет переписывать на `.zero?`, как-то вообще не согласен!
+Style/NumericPredicate:
+  Enabled: false
+
+Style/SymbolArray:
+  # Предпочитаю полный синтаксис вместо %i[foo bar], пстоянно забываю что
+  # такое %i, %w, %g, %Ж, %П, %x, %y, %й, %н, %я.
+  # EnforcedStyle: brackets
+  # Хотя нет, стиль написания может быть любым, учись понимать и так и сяк.
+  Enabled: false
+
+# fail обычно бросает исключение, raise пребрасывает после отлова при
+# необходимости.
+Style/SignalException:
+  Enabled: false
+
+# Что может быть более привычным чем простой if
+Style/NegatedIf:
+  Enabled: false
+
+Style/SymbolProc:
+  # Аргументы отдельно блоки отдельно:
+  # something.do_something(foo) { |o| o.bar }
+  # AllowMethodsWithArguments: true
+  # Отключена проверка стиля передачи блоков в метод, и так и сяк должно быть
+  # понятным.
+  Enabled: false
+
+# Короткий синтаксис для слабаков! =) на мой взгляд, когда в одном хэш смешан
+# короткий и полный синтаксис, тогда код читается рывками (читаем один
+# синтаксис, преключаемся на другой, продолжать читать и потом вдруг обратно).
+# Возможно дело привычки.
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+
+# Разбивать метод или блок на подметоды только ради красоты кода не хочу, если
+# всё что нужно сделать в методе задокумментировано и это не дублирующий код а
+# просто большая отдельная задача, то почему бы и не 2000 строк.
+Metrics/MethodLength:
+  Max: 100
+Metrics/BlockLength:
+  Max: 300
+Metrics/CyclomaticComplexity:
+  Max: 30
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 300
+Metrics/ModuleLength:
+  Max: 300
+
+# Assignment - присвоения, в том числе +=...
+# Branch - явное прямое ветвление программы (вызов методов).
+# Condition - логические выражения
+# AbcSize = Math.sqrt(A * A + B * B + C * C)
+Metrics/AbcSize:
+  # Enabled: false
+  Max: 100
+  CountRepeatedAttributes: false
+
+# Я так привык — каждый пробел (отступ) должен быть обоснован, а не нафигачен
+# до «красивого» отступа.
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: key
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+# Терпеть не могу пробелы ради выравнивания, предпочитаю устанавливать
+# необходимое количество отступов (отступ в ruby − кратен двум пробелам).
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: indented
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Эммм, это ж короткий синтаксис, нахуй пробелы! array.map{|x| x.id}
+Layout/SpaceBeforeBlockBraces:
+  EnforcedStyle: no_space
+Layout/SpaceInsideBlockBraces:
+  EnforcedStyle: no_space
+  SpaceBeforeBlockParameters: false
+
+# На какой вертикали начался блок, на той и должен закрываться.
+Layout/BlockAlignment:
+  EnforcedStyleAlignWith: start_of_block

data/.ruby-version

@@ -1 +1 @@
-2.5.3
+2.7.8

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## [2.4.0](https://github.com/Zlatov/nested_array/tree/2.4.0) (2023-01-19)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.3.0...2.4.0)
+
+## [2.3.0](https://github.com/Zlatov/nested_array/tree/2.3.0) (2023-01-18)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.2.1...2.3.0)
+
+**Security fixes:**
+
+- \[Security\] Bump activesupport from 5.2.4.1 to 6.0.3.2 [\#5](https://github.com/Zlatov/nested_array/pull/5) ([dependabot-preview[bot]](https://github.com/apps/dependabot-preview))
+
+## [2.2.1](https://github.com/Zlatov/nested_array/tree/2.2.1) (2023-01-14)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.2.0...2.2.1)
+
+## [2.2.0](https://github.com/Zlatov/nested_array/tree/2.2.0) (2020-03-10)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/1.1.0...2.2.0)
+
+## [1.1.0](https://github.com/Zlatov/nested_array/tree/1.1.0) (2020-02-14)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.0.4...1.1.0)
+
+## [2.0.4](https://github.com/Zlatov/nested_array/tree/2.0.4) (2020-01-19)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.0.3...2.0.4)
+
+## [2.0.3](https://github.com/Zlatov/nested_array/tree/2.0.3) (2020-01-19)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/2.0.2...2.0.3)
+
+## [2.0.2](https://github.com/Zlatov/nested_array/tree/2.0.2) (2020-01-19)
+
+[Full Changelog](https://github.com/Zlatov/nested_array/compare/784a121dd18007e7e7d113f03c665eb39aa9b018...2.0.2)
+
+
+
+\* *This Changelog was automatically generated       by [github_changelog_generator]      (https://github.com/github-changelog-generator/github-changelog-generator)*

data/Gemfile

@@ -3,3 +3,10 @@ source "https://rubygems.org"
 gemspec
 
 gem 'activesupport', '~> 6.0'
+
+group :test do
+  gem 'rspec', '~> 3.10'
+end
+
+# Следим за кодом
+gem 'rubocop', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nested_array (2.2.1)
+    nested_array (3.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,30 +12,50 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
+    ast (2.4.2)
     awesome_print (1.8.0)
     byebug (11.0.1)
     concurrent-ruby (1.1.6)
-    diff-lcs (1.3)
+    diff-lcs (1.5.0)
     i18n (1.8.3)
       concurrent-ruby (~> 1.0)
     minitest (5.14.1)
+    parallel (1.22.1)
+    parser (3.2.1.1)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
     rake (10.5.0)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.0)
-      rspec-support (~> 3.9.0)
-    rspec-expectations (3.9.0)
+    regexp_parser (2.7.0)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.28.2)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.17.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.17.0)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.13.0)
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
+    unicode-display_width (2.4.2)
     zeitwerk (2.3.0)
 
 PLATFORMS
@@ -48,7 +68,8 @@ DEPENDENCIES
   byebug (~> 11.0)
   nested_array!
   rake (~> 10.0)
-  rspec (~> 3.9)
+  rspec (~> 3.10)
+  rubocop
 
 BUNDLED WITH
    2.1.4

data/README-ru-old.md

@@ -0,0 +1,333 @@
+# NestedArray
+
+Предназначен для преобразования в древовидную структуру плоских данных описанных
+по паттерну «Список смежности» (Adjacency List), то есть в нодах указа предок
+`parent_id`. Например:
+
+```ruby
+[
+  {id: 1, parent_id: nil, name: 'first', …},
+  {id: 2, parent_id:   1, name: 'second', …},
+  {id: 3, parent_id:   1, name: 'third', …}
+]
+# ↓ ↓ ↓
+[
+  {id: 1, parent_id: nil, name: 'first', children: [
+    {id: 2, parent_id:   1, name: 'second', …},
+    {id: 3, parent_id:   1, name: 'third', …}
+  ], …}
+]
+```
+
+
+
+
+## Установка
+
+Добавте строку в _Gemfile_ вашего приложения:
+
+```ruby
+# Работа с древовидными массивами.
+gem "nested_array", "~> 3.0"
+```
+
+И затем выполните `bundle install`.
+
+Или установите его как `gem install nested_array`
+
+Если вы планируете использовать скромный CSS гема, добавте в
+файл _app/assets/stylesheets/application.scss_:
+
+```css
+/* Отображение древовидных массивов. */
+@import "nested_array";
+```
+
+
+## Использование
+
+<a name="methods"></a>
+* Список методов
+  * [to_nested](#to_nested) — преобразует плоскую структуру во вложенную;
+  * [each_nested](#each_nested) — перебирает вложенную стуктуру;
+  * [each_nested!](#each_nested) — перебирает вложенную стуктуру, предоставляя доступ к исходным данным;
+  * [nested_to_html](#nested_to_html) — преобразует вложенную структуру в html вёрстку (многоуровневый список `<ul><li>…`);
+  * [nested_to_options](#nested_to_options) — преобразует вложенную структуру в массив для формирования опций html-тега `<select>` с псевдографикой;
+  * [nested_to_collection_select](#nested_to_collection_select) — преобразует вложенную структуру в плоскую но добавляет псевдографику в тектовое поле для формирования тэга `<select>`;
+  * [concat_nested](#concat_nested) — скеивание вложенных структур, ноды склеиваются если путь к ним одинаков.
+* Вывод
+  * Вложенный список ul > li
+
+
+### Список методов
+
+<a name="to_nested"></a>
+#### to_nested [↑](#methods "К методам")
+
+Преобразует плоскую структуру во вложенную.
+
+```ruby
+a = [{'id' => 1, 'parent_id' => nil}]
+a = NestedArray::Array.new a
+b = a.to_nested
+```
+
+__Опции__
+
+У каждой ноды вложенной структуры есть базовые свойства, такие как
+идентификатор, идентификатор предка и другие. Для доступа к этим данным
+используются ключи, которые можно настроить как в примере ниже. По умолчанию
+используются следующие __строковые__ (_чувствительны к string/symbol_) ключи:
+
+```ruby
+b = a.to_nested({
+  id: 'id',               # указывает какое свойство ноды является идентификатором;
+  parent_id: 'parent_id', # -//- предком;
+  children: 'children',   # -//- массивом потомков;
+  level: 'level'          # -//- дополнительным свойством с уровнем вложенности;
+  root_id: nil            # определяет что является корнем для построения дерева,
+                          # например, для построения ветви корнем корнем
+                          # является идентификатор одной из нод.
+})
+```
+
+Дополнительные опции преобразования:
+
+```ruby
+b = a.to_nested({
+  hashed: false,    # потомки могут храниться не в массиве а в хэше;
+  add_level: false, # добавляет в ноду информацию о уровене вложенности ноды;
+})
+```
+
+
+
+
+<a name="each_nested"></a>
+#### each_nested [↑](#methods "К методам")
+
+Перебирает вложенную стуктуру.
+
+```ruby
+nested.each_nested do |node, parents, level, is_last_children|
+  puts node             # > {'id' => ...}
+  puts parents          # > [{'id' => ...}]
+  puts level            # > 0
+  puts is_last_children # > false
+end
+```
+
+
+
+
+<a name="nested_to_html"></a>
+#### nested_to_html [↑](#methods "К методам")
+
+Формирует _html_-код для вывода вложенных структур с использованием вложенных друг в друга списков `<ul>`.
+
+__Пример__
+
+```ruby
+[
+  {'id' => 1, 'parent_id' => nil, 'name' => 'first'},
+  {'id' => 2, 'parent_id' =>   1, 'name' => 'second'},
+  {'id' => 3, 'parent_id' =>   1, 'name' => 'third'}
+].to_nested.nested_to_html do |node|
+  node['name']
+end
+```
+
+Вернёт
+
+```html
+	<li>first
+		<ul>
+			<li>second</li>
+			<li>third</li>
+		</ul>
+	</li>
+```
+
+__Расширенный пример__
+
+```ruby
+.nested_to_html li: '<li class="my">', _ul: '<i></i></ul>' do |node, parents, level|
+  block_options = {}
+  block_options[:li] = '<li class="my current">' if node['id'] == 2
+  [
+  	"id: #{node['id']}, #{node['name']}, parent name: #{parents[level]&.[]('name')}",
+  	block_options
+  ]
+end
+```
+
+__Опции__
+
+Все опции могут быть аргументами метода, и только некоторые опции влияют на результат через блок — на лету (последняя строка блока).
+
+```ruby
+tabulated: true,
+inline: false,
+tab: "\t",
+ul:  '<ul>', # может задаваться блоком
+_ul: '</ul>',
+li:  '<li>', # может задаваться блоком
+_li: '</li>',
+```
+
+
+
+
+<a name="nested_to_options"></a>
+#### nested_to_options [↑](#methods "К методам")
+
+Формирования опций для html-тега &lt;select&gt;
+
+Возвращает массив с псевдографикой, позволяющей вывести древовидную структуру.
+
+```ruby
+
+[['option_text1', 'option_value1'],['option_text2', 'option_value2'],…]
+```
+
+__Опции__
+
+```ruby
+option_value: 'id', # Что брать в качестве значений при формировании опций селекта.
+option_text: 'name',
+```
+
+
+
+
+<a name="nested_to_collection_select"></a>
+#### nested_to_collection_select [↑](#methods "К методам")
+
+Преобразует вложенную структуру данных в плоскую, но добавляет в значение поля
+отвечающего за текстовое представление (:name) псевдографику древовидной
+структуры.
+
+Это позволяет вывести тэг select в сносном виде для использования с вложенными
+структурами.
+
+Пример с хелпером `collection_select`
+
+```rb
+<%= form.collection_select :catalog_ids,
+  Catalog.all.to_a.to_nested.nested_to_collection_select, :id, :name,
+  {
+    # prompt: true
+    # include_blank: true
+  },
+  {
+    multiple: true,
+    size: 10
+  }
+%>
+```
+
+Пример с хелпером `select` в сочетании с `options_from_collection_for_select`
+
+```erb
+<% catalogs = Catalog.all.to_a %>
+<%= form.select :catalog_ids,
+  options_from_collection_for_select(
+    catalogs.to_nested.nested_to_collection_select, :id, :name,
+    disabled: catalogs.select{|x| x.hidden?}.pluck(:id),
+    selected: form.object.catalog_ids
+  ),
+  {
+    # prompt: true
+    # include_blank: true
+  },
+  {
+    multiple: true,
+    size: 10
+  }
+%>
+```
+
+
+
+
+<a name="concat_nested"></a>
+#### concat_nested [↑](#methods "К методам")
+
+Скеивание вложенных структур.
+
+* Ноды склеиваются если путь к ним одинаков;
+* Путь определяется из сложения Текстов (конфигурируемо через :path_key);
+
+__Опции__
+
+```ruby
+path_separator: '-=path_separator=-',
+path_key: 'text',
+```
+
+
+
+### Вывод
+
+#### Вложенный список ul-li
+
+![Screenshot](doc/images/01.png)
+
+```ruby
+<ul>
+  <% @catalogs.to_a.to_nested.each_nested do |node, origin| %>
+    <%= node.before -%>
+    <%= node.name -%>
+    <%= node.after -%>
+  <% end %>
+</ul>
+```
+
+![Screenshot](doc/images/02.png)
+
+#### Вложенный расскрывающийся список
+
+```ruby
+<ul class="nested_array-details">
+  <% @catalogs.to_a.to_nested.each_nested details: true do |node, origin| %>
+    <%= node.before -%>
+    <%= node.name -%>
+    <%= node.after -%>
+  <% end %>
+</ul>
+```
+
+![Screenshot](doc/images/03.png)
+
+Если необходимо открыть некоторые узлы
+
+```ruby
+<ul class="nested_array-details">
+  <% @catalogs.to_a.to_nested.each_nested details: true do |node, origin| %>
+    <%= node.before -%>
+    <%= node.name -%>
+    <%= node.after(open: node.is_has_children) -%>
+  <% end %>
+</ul>
+```
+
+![Screenshot](doc/images/04.png)
+
+
+## Разработка
+
+…
+
+
+
+
+## Содействие
+
+…
+
+
+
+
+## Лицензия
+
+В соответствии с условиями [лицензии MIT](https://opensource.org/licenses/MIT).