yml_builder 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b10e44faa9d509c11bbe34e4e0add97bb5956f15
-  data.tar.gz: 9e7634b0d218b487480bb242a404e9705d5a7991
+  metadata.gz: f345347a313447611efffb080f9fe5c71bd41702
+  data.tar.gz: aaa36cfb2590870a030f1b39756114ea43e06f74
 SHA512:
-  metadata.gz: 14847041d19be93067fb9f0c2ca4cab96030115071191841b55bfcd0fbe0057c90b598140be1db47fad77018bb5551568271881b182f1a276559425d2b217f8f
-  data.tar.gz: 1239542340171ddf325f154722a8678787e06d50e19731c699c656ad4180c200522545b05d23043599b37424a32d7ae0e7c817a73624f78d7979378848a7e7df
+  metadata.gz: fa385fbdb34c75143286a4fb69d1ceed58df439faed06663adf657f0b4456201947d2d23e3a8f249a9d59bb34344aa4f57485994a6453dd304d2a13256019cd0
+  data.tar.gz: dda2773df6b790eb697709c5790275f5368bae2dfd1c9697cb834bccc83f868fc8452da1fcbd3b7549ecb5515eb4844fed3d32e48a70dd9ee023a70989e4e94f

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.1 (2015-05-14)
+
+* Добавлен метод .categories.has?, который проверяет наличие категории в формируемом прайс-листе.
+
+
 ## 0.1.0 (2015-05-11)
 
 * Начальная версия

data/lib/yml_builder/categories.rb

@@ -1,7 +1,12 @@
+# Класс обеспечивает добавление в парйс-лист Yandex.Market категорий Интернет-магазинов
+
 module YmlBuilder
   class Categories
     # Переменная содержит список id категорий, для которых необходимо формировать прайс-лист.
     # Если переменная пуста, то включаются все категории
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.categories.filter = [1, 3, 4, 5]
     attr_reader :filter
 
     def initialize(stats)
@@ -9,6 +14,17 @@ module YmlBuilder
       init_class
     end
 
+    # Метод добавляет категорию Интернет-магазина в прайс-лист с учетом выставленных в значении filter настроек.
+    #
+    # @param [Hash] opts параметры категорий Интернет-магазина
+    # @option opts [Object] :id идентификатор категории (обязательно)
+    # @option opts [Integer] :parent_id идентификатор родительской категории (опционально)
+    # @option opts [String] :name название категории (обязательно)
+    # @return [Boolean] true, если категория была добавлена, и false, если добавление запрещено в filter
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.categories.add(id: 1, name: 'Игрушки')
+    #   price.categories.add(id: 2, name: 'Игрушки для девочек', parent_id: 1)
     def add(opts = {})
       return false unless can_add?(opts[:id])
       allow = [:id, :parent_id, :name]
@@ -34,6 +50,9 @@ module YmlBuilder
     # Filter может принимать значения nil или [], тогда считается, что допустимо включение в прайс-лист
     # всех товаров.
     # @param [Array] allow массив id категорий, который должны попадать в результирующий прайс-лист
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.categories.filter = [1, 3, 4, 5]
     def filter=(allow)
       @filter = allow || Array.new
     end
@@ -41,7 +60,7 @@ module YmlBuilder
     # Метод формирует фрагмент YML файла каталога Яндекс.Маркет, содержащий список категорий
     #
     # @param [Integer] ident отступ от левого края в символах
-    # @return [String] фрагмент YML файла каталога Яндекс.Маркет, содержащий список категорий
+    # @return [String] фрагмент YML файла каталога Яндекс.Маркет
     def to_yml(ident = 4)
       out = Array.new
       out << '<categories>'
@@ -61,6 +80,14 @@ module YmlBuilder
       out.join("\n")
     end
 
+    # Метод возвращает true, если категория, передаваемая в качестве параметра, уже добавлена в прайс-лист
+    #
+    # @param [Object] id идентификатор категории
+    # @return [Boolean] true, если категория с заданным id уже была добавлена в прайс-лист
+    def has?(id)
+      @params[id].nil? ? false : true
+    end
+
     private
 
     def init_class

data/lib/yml_builder/common.rb

@@ -1,4 +1,4 @@
-module YmlBuilder
+module YmlBuilder # :nodoc:
   class Common
 
     def self.encode_special_chars(out)

data/lib/yml_builder/common_offer.rb

@@ -1,29 +1,34 @@
 module YmlBuilder
   class CommonOffer
+    # Уникальный идентификатор товара
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   offer.id = 10
     attr_accessor :id
+    # Уникальный идентификатор типа товара, в соответствии с классификацией Yandex.MArket. Устанавливается в конструкторе
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   puts offer.type                             #=> 'simple'
     attr_accessor :type
+    # Наличие товара на складе
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   puts offer.available = true
     attr_accessor :available
     attr_accessor :bid
 
+    # Список обязательных полей для данного типа оффера
     attr_accessor :mandatories
 
     def initialize
       init_class
     end
 
-    def init_class
-      @params = Hash.new
-      @meta = Hash.new
-      @picture = Array.new
-
-      @id = 0
-      @type = 'unknown'
-      @available = false
-      @bid = nil
-
-      @mandatories = Array.new
-    end
-
+    # Метод добавляет ссылку на фотографию товара в конец списка, и ограничивает список 10-ю фотографиями
+    # @param [String] url ссылка на фотографию товара
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   offer.add_picture('http://example-site.ru/image1.jpg')
     def add_picture(url)
       @picture << url
       @picture.uniq!
@@ -31,6 +36,11 @@ module YmlBuilder
       @picture = @picture[0,9]
     end
 
+    # Метод добавляет ссылку на фотографию товара в начало списка, и ограничивает список 10-ю фотографиями
+    # @param [String] url ссылка на фотографию товара (на основную фотографию)
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   offer.add_cover_picture('http://example-site.ru/cover_image1.jpg')
     def add_cover_picture(url)
       @picture.unshift(url)
       @picture.uniq!
@@ -38,10 +48,45 @@ module YmlBuilder
       @picture = @picture[0,9]
     end
 
+    # Метод добавляет характеристики товара (для секции 'param')
+    #
+    # @param [String] name наименование параметра, например "Количество товара"
+    # @param [String] unit суффикс параметра, например "шт."
+    # @param [Object] value значение параметра
+    # @example Примеры использования
+    #   offer = YmlBuilder::Offer.new('simple')
+    #   offer.add_param(name: "Количество", unit: "шт.", value: 100)
+    #   offer.add_param(name: "Обложка", value: "мягкая")
     def add_param(name:, unit: nil, value:)
       @meta[name] = { unit: unit, value: value}
     end
 
+    # Метод формирует фрагмент YML файла каталога Яндекс.Маркет для одного товара
+    #
+    # @param [Integer] ident отступ от левого края в символах
+    # @return [String] фрагмент YML файла каталога Яндекс.Маркет
+    def to_yml(ident = 4)
+      out = Array.new
+      out << header_line
+
+      @params.each do |key, value|
+        if [:picture, :param].include?(key)
+          out += to_yml_subsections(key)
+        elsif @mandatories.include?(key)
+          out << to_yml_mandatories(key, value)
+        else
+          out << to_yml_optional(key, value)
+        end
+      end
+      out.compact!
+
+      out << footer_line
+      out.map! { |line| ' '.rjust(ident, ' ') + line }
+      out.join("\n")
+    end
+
+    private
+
     def method_missing(method_sym, *arguments, &block)
       if @params.include?(method_sym.to_s.gsub(/=$/, '').to_sym)
         processing_method(method_sym, arguments.first)
@@ -54,8 +99,8 @@ module YmlBuilder
       if method_sym.to_s.match(/=$/)
         key = method_sym.to_s.gsub(/=$/, '')
         warn "Предупреждение: url не должен превышать 512 символов" if key == 'url' && value.length > 512
-        warn "Предупреждение: price не может быть равен нулю" if key == 'price' && value.to_f == 0
-        warn "Предупреждение: weight не может быть равен нулю" if key == 'weight' && value.to_f == 0
+        warn "Предупреждение: price не может быть равен нулю (offer id #{@id})" if key == 'price' && value.to_f == 0
+        warn "Предупреждение: weight не может быть равен нулю (offer id #{@id})" if key == 'weight' && value.to_f == 0
         @params[key.to_sym] = value
       else
         @params[method_sym.to_s.gsub(/=$/, '').to_sym]
@@ -111,24 +156,17 @@ module YmlBuilder
       "  <#{key_xml}>#{::YmlBuilder::Common.encode_special_chars(value)}</#{key_xml}>"
     end
 
-    def to_yml(ident = 4)
-      out = Array.new
-      out << header_line
+    def init_class
+      @params = Hash.new
+      @meta = Hash.new
+      @picture = Array.new
 
-      @params.each do |key, value|
-        if [:picture, :param].include?(key)
-          out += to_yml_subsections(key)
-        elsif @mandatories.include?(key)
-          out << to_yml_mandatories(key, value)
-        else
-          out << to_yml_optional(key, value)
-        end
-      end
-      out.compact!
+      @id = 0
+      @type = 'unknown'
+      @available = false
+      @bid = nil
 
-      out << footer_line
-      out.map! { |line| ' '.rjust(ident, ' ') + line }
-      out.join("\n")
+      @mandatories = Array.new
     end
 
   end

data/lib/yml_builder/currencies.rb

@@ -5,25 +5,28 @@ module YmlBuilder
       init_class
     end
 
-    def init_class
-      @params = Hash.new
-
-      @params[:rur] = nil
-      @params[:rub] = nil
-      @params[:usd] = nil
-      @params[:eur] = nil
-      @params[:uah] = nil
-      @params[:kzt] = nil
-    end
+    # Метод формирует фрагмент YML файла каталога Яндекс.Маркет, содержащий список валют
+    #
+    # @param [Integer] ident отступ от левого края в символах
+    # @return [String] фрагмент YML файла каталога Яндекс.Маркет
+    def to_yml(ident = 4)
+      out = Array.new
+      out << '<currencies>'
 
-    def method_missing(method_sym, *arguments, &block)
-      if @params.include?(method_sym.to_s.gsub(/=$/, '').to_sym)
-        processing_method(method_sym, arguments.first)
-      else
-        super
+      @params.each do |key, value|
+        out << "  <currency id=#{key.to_s.upcase.inspect} rate=#{value.to_s.upcase.inspect}/>" unless value.nil?
       end
+      warn "Предупреждение: не указано ни одной валюты в секции 'currencies'" if out.count == 1
+
+      out << '</currencies>'
+
+      out.map! { |line| line = ' '.rjust(ident, ' ') + line }
+
+      out.join("\n")
     end
 
+    private
+
     def valid?(method_sym, allow, value)
       return true if value.to_s.match(/^\s*[+-]?((\d+_?)*\d+(\.(\d+_?)*\d+)?|\.(\d+_?)*\d+)(\s*|([eE][+-]?(\d+_?)*\d+)\s*)$/)
       return true if allow.include?(value)
@@ -43,20 +46,23 @@ module YmlBuilder
       end
     end
 
-    def to_yml(ident = 4)
-      out = Array.new
-      out << '<currencies>'
-
-      @params.each do |key, value|
-        out << "  <currency id=#{key.to_s.upcase.inspect} rate=#{value.to_s.upcase.inspect}/>" unless value.nil?
-      end
-      warn "Предупреждение: не указано ни одной валюты в секции 'currencies'" if out.count == 1
-
-      out << '</currencies>'
+    def init_class
+      @params = Hash.new
 
-      out.map! { |line| line = ' '.rjust(ident, ' ') + line }
+      @params[:rur] = nil
+      @params[:rub] = nil
+      @params[:usd] = nil
+      @params[:eur] = nil
+      @params[:uah] = nil
+      @params[:kzt] = nil
+    end
 
-      out.join("\n")
+    def method_missing(method_sym, *arguments, &block)
+      if @params.include?(method_sym.to_s.gsub(/=$/, '').to_sym)
+        processing_method(method_sym, arguments.first)
+      else
+        super
+      end
     end
 
   end

data/lib/yml_builder/offer.rb

@@ -1,3 +1,6 @@
+# Модуль является рамочным. При создании товара данного типа, в реальности
+# будет возвращен класс товара заданного типа
+
 module YmlBuilder
   class Offer
 

data/lib/yml_builder/offer_simple.rb

@@ -1,4 +1,4 @@
-module YmlBuilder
+module YmlBuilder # :nodoc:
   class OfferSimple < YmlBuilder::CommonOffer
 
     def initialize

data/lib/yml_builder/offers.rb

@@ -1,3 +1,6 @@
+# Модуль управления карточками товара разного типа. По сути - это класс-массив, в котором
+# хранятся все товары
+
 module YmlBuilder
   class Offers
 
@@ -7,10 +10,12 @@ module YmlBuilder
       init_class
     end
 
-    def init_class
-      @offers = Hash.new
-    end
-
+    # Метод добавляет товар в прайс-лист с учетом выставленных в значении filter настроек.
+    #
+    # @param [{YmlBuilder::CommonOffer}] offer карточка товара
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.offers.add(offer)
     def add(offer)
       return false unless @categories.can_add?(offer.category_id)
       @offers[offer.id] = offer
@@ -24,6 +29,10 @@ module YmlBuilder
       true
     end
 
+    # Метод формирует фрагмент YML файла каталога Яндекс.Маркет для всего списка товаров
+    #
+    # @param [Integer] ident отступ от левого края в символах
+    # @return [String] фрагмент YML файла каталога Яндекс.Маркет
     def to_yml(ident = 4)
       @offers = @offers.sort_by { |id, offer| id }
 
@@ -38,5 +47,13 @@ module YmlBuilder
       out.join("\n")
     end
 
+
+    private
+
+
+    def init_class
+      @offers = Hash.new
+    end
+
   end
 end

data/lib/yml_builder/shop.rb

@@ -5,6 +5,35 @@ module YmlBuilder
       init_class
     end
 
+    # Метод формирует фрагмент YML файла каталога Яндекс.Маркет для описания Интернет-магазина
+    #
+    # @return [String] фрагмент YML файла каталога Яндекс.Маркет
+    def to_yml
+      out = Array.new
+      out << '  <shop>'
+
+      @params[:m].each do |key, value|
+        raise "Ошибка секции 'company': не заполнено значение для обязательного ключа #{key.to_s.inspect}" if value == ''
+        out << "    <#{key}>#{::YmlBuilder::Common.encode_special_chars(value)}</#{key}>"
+      end
+
+      @params[:o].each do |key, value|
+        unless value.nil?
+          out << "    <#{key}>#{::YmlBuilder::Common.encode_special_chars(value)}</#{key}>"
+        end
+      end
+
+      out << '    {replace_currencies}'
+      out << '    {replace_categories}'
+      out << '    {replace_local_delivery_cost}'
+      out << '    {replace_offers}'
+      out << '  </shop>'
+      out.join("\n")
+    end
+
+
+    private
+
     def init_class
       @params = Hash.new
 
@@ -43,29 +72,6 @@ module YmlBuilder
       end
     end
 
-    def to_yml
-      out = Array.new
-      out << '  <shop>'
-
-      @params[:m].each do |key, value|
-        raise "Ошибка секции 'company': не заполнено значение для обязательного ключа #{key.to_s.inspect}" if value == ''
-        out << "    <#{key}>#{::YmlBuilder::Common.encode_special_chars(value)}</#{key}>"
-      end
-
-      @params[:o].each do |key, value|
-        unless value.nil?
-          out << "    <#{key}>#{::YmlBuilder::Common.encode_special_chars(value)}</#{key}>"
-        end
-      end
-
-      out << '    {replace_currencies}'
-      out << '    {replace_categories}'
-      out << '    {replace_local_delivery_cost}'
-      out << '    {replace_offers}'
-      out << '  </shop>'
-      out.join("\n")
-    end
-
 
   end
 end

data/lib/yml_builder/version.rb

@@ -1,3 +1,3 @@
 module YmlBuilder # :nodoc:
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/yml_builder/yml.rb

@@ -3,15 +3,30 @@
 
 module YmlBuilder
   class Yml
-    # Ссылка на класс, описывающий контакты Интернет-магазина
+    # Ссылка на класс, описывающий контакты Интернет-магазина ({YmlBuilding::Shop})
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.shop.phone = '+7 (123) 456-7890'
     attr_reader :shop
-    # Ссылка на класс, описывающий категории
+    # Ссылка на класс, описывающий категории (YmlBuilding::Categories)
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.categories.add(id: 1, name: "Игрушки")
+    #   price.categories.add(id: 4, name: "Игрушки для девочек", parent_id: 1)
     attr_reader :categories
-    # Ссылка на класс, описывающий валюты
+    # Ссылка на класс, описывающий валюты ({YmlBuilding::Currencies})
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.currencies.rub = 1
+    #   price.currencies.usd = 55.04
+    #   price.currencies.eur = :cbrf
     attr_reader :currencies
-    # Ссылка на класс, управляющий товарами (офферами)
+    # Ссылка на класс, управляющий товарами (офферами) ({YmlBuilding::Offers})
     attr_reader :offers
     # Переменая, хранящая стоимость доставки в локации расположения Интернет-магазина
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.local_delivery_cost = 300
     attr_reader :local_delivery_cost
 
 
@@ -25,7 +40,7 @@ module YmlBuilder
     end
 
     # Метод устанавливает стоимость доставки в месте локации магазина. Например, если магазин находится в Москве,
-    #  то при указанни данной стоимости, она будет показана покупателям в этом же районе.
+    # то при указанни данной стоимости, она будет показана покупателям в этом же районе.
     #
     # @param [Float] value стоимость доставки в месте локации магазина
     # @return [None] нет
@@ -34,9 +49,12 @@ module YmlBuilder
     end
 
     # Метод возвращает статистику по результатам генерации прайс-листа: всего товаров, товаров в наличии, стоимость
-    #  товаров в наличии (без учета количества)
+    # товаров в наличии (без учета количества)
     #
     # @return [None] нет
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.stats                    #=> { :categories => 0, :total => 2, :available => 1, :price => 300.9 }
     def stats
       @stats.stats
     end
@@ -44,6 +62,9 @@ module YmlBuilder
     # Метод возвращает текстовую строку с прайс-листом в формате Яндекс.Маркет
     #
     # @return [String] строка с прайс-листом в формате utf-8
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.to_yml
     def to_yml
       out = @shop.to_yml
       out.gsub!(/^\s{0,100}\{replace\_currencies\}/, @currencies.to_yml)
@@ -58,6 +79,9 @@ module YmlBuilder
     #
     # @param [String] filename название файла для записи прайс-листа
     # @return [None] нет
+    # @example Примеры использования
+    #   price = YmlBuilder::Yml.new
+    #   price.save('price.yml')
     def save(filename)
       File.open(filename, 'w:windows-1251') {|f| f.write(to_yml) }
     end

data/test/test_yml.yml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="windows-1251"?>
 <!DOCTYPE yml_catalog SYSTEM "shops.dtd">
-<yml_catalog date="2015-05-11 14:57">
+<yml_catalog date="2015-05-11 17:24">
   <shop>
     <name>������� ����</name>
     <company>��� &apos;���� &amp; ������&apos;</company>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yml_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Stan Zhuravlev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-11 00:00:00.000000000 Z
+date: 2015-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -40,7 +40,7 @@ dependencies:
         version: '10.0'
 description: |-
   Библиотека содержит набор классов для формирования и валидации прайс-листов
-                            в формате Яндекс YAML (Яндекс.Маркет).
+                            в формате Яндекс YAML (Yandex.Market).
                             Текущая версия поддерживает только упрощенные товарные карточки.
 email:
 - stan@post-api.ru