st_tools 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dbc4df1cb453510d365fd64c9706ff8f6a733412
-  data.tar.gz: 999050e842607f77143e00d9881174f8489a30d8
+  metadata.gz: b9636bb4e4a7eca384e243785b78add9c259fee4
+  data.tar.gz: c336f6ba172b1df7cf029f0ab62704e473e02aef
 SHA512:
-  metadata.gz: 2f46739ed694b711f20045b4e82f5d0bdfd0cfd8e504d45bf875dac97743e7f6dd9cfabae93080a6b7b41e54384fd0daeba74cb065f2272cbdbac38343f4f07e
-  data.tar.gz: ecf50eaa21dd3672fe40d0e42a4905619ea944bc4996d58c0a949391b6f9f6cafb050a6e880136e3656663bb732368eb5d0b5fd9cbddfd79f3e3778e4abacdcb
+  metadata.gz: 50aaa34a9388dffdf0bc3459bfbdefa5240ab9e1437af0395871e4967119b1fb1a633d1dd4feccb05c56d060f69265785f70c889f1d179b6e7fd7396dd606180
+  data.tar.gz: 046ff39698e836e0f6753ccd3e80520c42151b647d0daa6dfa3efc7ffa311e816c809d9c9aa6cc6cfc66d3fc6aec5de62f3b17e7f72de97a1aba6b76cd89263e

data/README.md

@@ -1,10 +1,9 @@
 # StTools
 
-Данные гем содержит методы, обеспечивающие:
-- преобразование строк с учетом русского языка
-- формирования человеко-удобной информации
-- получения разных системных характеристик CLI-приложений
-- управление прогресс-баром CLI-приложений
+Библиотека StTools предназначена для поддержки CLI- и Rails-приложений. Она обеспечивает
+различное преобразование строк с учетом русского языка, формирование человеко-удобного представления времени и чисел,
+получения разных системных характеристик CLI-приложений (память, размер экрана терминала),
+управление прогресс-баром CLI-приложений.
 
 ## Установка
 
@@ -14,11 +13,11 @@
 gem 'st_tools'
 ```
 
-Установите гем cредствами Bundler:
+Установить гем cредствами Bundler:
 
     $ bundle
 
-Или установите его отдельно:
+Или установить его отдельно:
 
     $ gem install st_tools
 
@@ -30,8 +29,8 @@ gem 'st_tools'
 ## Использование
 
 Часть методов библиотеки поддерживают русскую и английскую локализацию.
-Поскольку все методы StTools могут вызываться без создания класса - конструктор не вызывается.
-Поэтому перед работой библиотеки рекомендуется вызвать StTools::Setup.setup(:ru или :en).
+Поскольку все методы StTools могут вызываться без создания экземпляра класса - вызов конструктура класса отсутствует.
+Поэтому перед работой библиотеки рекомендуется вызвать StTools::Setup.setup(:ru или :en) для загрузки файлов локализации.
 
 ### StTools::Human
 
@@ -152,21 +151,25 @@ StTools::String.caps('санКТ-петерБург')              # => "Сан
 ```
 
 Для реализации деморежимов различных приложений иногда надо скрыть реальный результат.
-Для это можно использовать метод hide_text
+Для это можно использовать метод hide
 
 ```ruby
-StTools::String.hide_text('Краснодар')              # => "Кра*но*ар"
+StTools::String.hide('Краснодар')              # => "Кра*но*ар"
 ```
 
 В Ruby отсутствует метод перевода строки пользователя в тип Boolean.
 
 ```ruby
-StTools::String.to_bool('true')              # => true
-StTools::String.to_bool('on')                # => true
-StTools::String.to_bool('1')                 # => true
-StTools::String.to_bool('faLSE')             # => false
-StTools::String.to_bool('off')               # => false
-StTools::String.to_bool('0')                 # => false
+StTools::String.to_bool("True")    # => true
+StTools::String.to_bool("trUE")    # => true
+StTools::String.to_bool("on")      # => true
+StTools::String.to_bool("1")       # => true
+StTools::String.to_bool("Да")      # => true
+StTools::String.to_bool("Yes")     # => true
+StTools::String.to_bool("false")   # => false
+StTools::String.to_bool("fALse")   # => false
+StTools::String.to_bool("oFF")     # => false
+StTools::String.to_bool("0")       # => false
 ```
 
 Если пользователь введет в качестве входного параметра перечисление, следующий метод разобъет его на токены,

data/lib/modules/string.rb

@@ -51,7 +51,7 @@ module StTools
       # @example Сокрытие части строки
       #   "Владимир".hide #=> "Вл*ди*ир"
       def hide
-        ::StTools::String.hide_text(self)
+        ::StTools::String.hide(self)
       end
 
       # Метод разделяет строку на подстроки, и нормализует кажду подстроку через #normalize

data/lib/st_tools/common.rb

@@ -2,11 +2,11 @@ module StTools
   class Common
 
     # Функция переводит хеши с несколькими уровнями вложения в плоский хэш, в котором
-    # глубина структуры заменяется ключами, разделенными точкой
-    # Источник: https://gist.github.com/lucabelmondo/4161211
+    # глубина структуры заменяется ключами, разделенными точкой.
+    # За основу взят не-рекурсивный алгоритм отсюда: https://gist.github.com/lucabelmondo/4161211
     #
     # @param [Hash] hash для перевода ключей в плоский вид, разделенный точками
-    # @return [Hash] Hash вида "key.subkey.subsubkey" => value
+    # @return [Hash] возвращается одномерная Hash-структура вида "key.subkey.subsubkey" => value
     def self.flatten_hash(hash)
       result_iter = {}
       paths = hash.keys.map { |key| [key] }

data/lib/st_tools/fias.rb

@@ -6,61 +6,76 @@ module StTools
     # Функции получения aoguid адресного объекта
     #
     #-------------------------------------------------------------
-    # Функция возвращает aoguid Москвы в системе ФИАС
+
+    # Функция возвращает aoguid города федерального значения Москва в системе ФИАС
     #
     # @return [String] aoguid г. Москва
     def self.moscow_aoguid
       return self.federal_cities['msk']
     end
 
-    # Функция возвращает aoguid Санкт-Питербурга в системе ФИАС
+    # Функция возвращает aoguid города федерального значения Санкт-Питербурга в системе ФИАС
     #
     # @return [String] aoguid г. Санкт-Питербурга
     def self.spb_aoguid
       return self.federal_cities['spb']
     end
 
-    # Функция возвращает aoguid Севастополя в системе ФИАС
+    # Функция возвращает aoguid города федерального значения Севастополя в системе ФИАС
     #
     # @return [String] aoguid г. Севастополь
     def self.sevastopol_aoguid
       return self.federal_cities['svs']
     end
 
-    # Функция возвращает aoguid Байконура в системе ФИАС
+    # Функция возвращает aoguid города федерального значения Байконура в системе ФИАС
     #
     # @return [String] aoguid г. Байконур
     def self.baikonur_aoguid
       return self.federal_cities['bai']
     end
 
-    #-------------------------------------------------------------
-    #
-    # Функции валидации типа адресного объекта
+
+    # Метод проверяет, является ли aoguid городом федерального значения
     #
-    #-------------------------------------------------------------
+    # @param [String] aoguid адресного объекта из таблицы addrobj ФИАС
+    # @return [Boolean] true, если объект - любой из городов федерального значения
     def self.federal?(aoguid)
       return true if self.federal_cities.values.include?(aoguid)
       return false
     end
 
+    # Метод проверяет, является ли aoguid городом федерального значения Москва
+    #
+    # @param [String] aoguid адресного объекта из таблицы addrobj ФИАС
+    # @return [Boolean] true, если объект - Москва
     def self.moscow?(aoguid)
       return true if self.federal_cities['msk'] == aoguid
       return false
     end
 
-    # @param [aoguid] aoguid адресного объекта из таблицы addrobj ФИАС
-    # @return [bool] true, если объект - Санкт-Петербург
+    # Метод проверяет, является ли aoguid городом федерального значения Санкт-Петербург
+    #
+    # @param [String] aoguid адресного объекта из таблицы addrobj ФИАС
+    # @return [Boolean] true, если объект - Санкт-Петербург
     def self.spb?(aoguid)
       return true if self.federal_cities['spb'] == aoguid
       return false
     end
 
+    # Метод проверяет, является ли aoguid городом федерального значения Севастополь
+    #
+    # @param [String] aoguid адресного объекта из таблицы addrobj ФИАС
+    # @return [Boolean] true, если объект - Севастополь
     def self.sevastopol?(aoguid)
       return true if self.federal_cities['svs'] == aoguid
       return false
     end
 
+    # Метод проверяет, является ли aoguid городом федерального значения Байконур
+    #
+    # @param [String] aoguid адресного объекта из таблицы addrobj ФИАС
+    # @return [Boolean] true, если объект - Байконур
     def self.baikonur?(aoguid)
       if self.federal_cities['bai'] == aoguid
         return true
@@ -69,30 +84,39 @@ module StTools
     end
 
 
-    #--------------------------------------------------------------
+    # Метод проверяет, имеет ли переданная строка тип UUID
     #
-    # Функции определения типа переданного значения
-    #
-    #--------------------------------------------------------------
-    def self.uuid?(id)
-      if id.match(/[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}/i)
+    # @param [String] text исходная строка
+    # @return [Boolean] true, если строка имеет тип UUID
+    # @example Примеры использования
+    #   StTools::Fias.uuid?('0c5b2444-70a0-4932-980c-b4dc0d3f02b5') #=> true
+    #   StTools::Fias.uuid?('Hello, word!') #=> false
+    def self.uuid?(text)
+      return nil if text.nil?
+      if text.match(/[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}/i)
         return true
       end
       return false
     end
 
-    def self.postalcode?(id)
-      if id.to_s.strip.match(/^\d{6}$/)
+    # Метод проверяет, яаляется строка почтовым индексом
+    #
+    # @param [String] text исходная строка
+    # @return [Boolean] true, если строка является почтовым индексом
+    # @example Примеры использования
+    #   StTools::Fias.postalcode?('111141') #=> true
+    #   StTools::Fias.postalcode?('   141207') #=> true
+    #   StTools::Fias.postalcode?('Hello') #=> false
+    #   StTools::Fias.postalcode?('1234') #=> false
+    def self.postalcode?(text)
+      return nil if text.nil?
+      if text.to_s.strip.match(/^\d{6}$/)
         return true
       end
       return false
     end
 
-    #--------------------------------------------------------------
-    #
-    # Вспомогательные функции
-    #
-    #--------------------------------------------------------------
+
     private
 
     # noinspection RubyClassVariableUsageInspection

data/lib/st_tools/human.rb

@@ -2,10 +2,14 @@ module StTools
   class Human
 
 
-    # Функция возвращает форматированную строку из любого числа с суффиксом тыс., млн. и пр.
+    # Метод форматирует число, добавляя суффиксы 'тыс.', 'млн.' и пр.
     #
-    # @param [Integer] val значение
-    # @return [String] строка вида "512,4 кило"
+    # @param [Integer] val исходное числовое значение
+    # @return [String] строка вида "512,4 тыс."
+    # @example Примеры использования
+    #   StTools::Human.number(123)           #=> "123"
+    #   StTools::Human.number(14563)         #=> "14 тыс."
+    #   StTools::Human.number(763552638)     #=> "763.6 млн."
     def self.number(val)
       # todo: локлаизовать через i18N
       # noinspection RubyStringKeysInHashInspection
@@ -23,10 +27,14 @@ module StTools
       end
     end
 
-    # Функция возвращает форматированную строку из любого числа с объемом памяти.
+    # Метод форматирует число, добавляя суффиксы 'кбайт', 'Мбайт' и др.
     #
-    # @param [Integer] val значение в байтах
+    # @param [Integer] val исходное числовое значение в байтах
     # @return [String] строка вида "512,4 Мбайт"
+    # @example Примеры использования
+    #   StTools::Human.bytes(123)           #=> "123 байта"
+    #   StTools::Human.bytes(14563)         #=> "14 кбайт"
+    #   StTools::Human.bytes(763552638)     #=> "728.2 Мбайт"
     def self.bytes(val)
       # todo: локлаизовать через i18N
       # noinspection RubyStringKeysInHashInspection
@@ -44,7 +52,7 @@ module StTools
       end
     end
 
-    # Функция возвращает форматированную строку с объемом памяти, занимаемым текущим процессом (pid).
+    # Метод возвращает форматированную строку с объемом памяти, занимаемым текущим процессом (pid).
     #
     # @return [String] строка вида "512,4 Мбайт"
     def self.memory
@@ -52,12 +60,17 @@ module StTools
       return self.bytes(val)
     end
 
-    # Функция переводит DateTime в строку на русском или иных языках вида "4 дня 23 часа назад".
-    # Предварительно необходимо вызвать StTools.setup(:ru).
+    # Метод переводит DateTime в строку на русском или иных языках вида "4 дня 23 часа назад".
+    # Предварительно необходимо вызвать StTools.setup(:ru или :en).
     #
     # @param [DateTime] time время и дата
-    # @param [Boolean] ago добавление слова "назад" в конец строки
+    # @param [Boolean] ago true, если надо добавить слово "назад" в конец строки
     # @return [String] строка вида "3 дня 12 часов" или "3 дня 12 часов назад"
+    # @example Примеры использования
+    #   StTools::Setup.setup(:ru)
+    #   StTools::Human.ago_in_words(Time.now - 23, true)       #=> "23 секунды назад"
+    #   StTools::Human.ago_in_words(Time.now - 24553, false)   #=> 6 часов 49 минут"
+    #   StTools::Human.ago_in_words(Time.now)                  #=> "сейчас"
     def self.ago_in_words(time, ago = true)
       now = self.to_time(Time.now.strftime('%Y-%m-%d %H:%M:%S UTC'))
       slf = self.to_time(time.strftime('%Y-%m-%d %H:%M:%S UTC'))
@@ -70,25 +83,41 @@ module StTools
       pair.join(' ')
     end
 
-    # Функция переводит DateTime в строку на русском или иных языках. Предварительно необходимо вызвать
-    # StTools.setup(:ru).
+    # Метод переводит DateTime в строку на русском или иных языках. Предварительно необходимо вызвать
+    # StTools.setup(:ru или :en).
     #
-    # @param [DateTime] time время и дата
-    # @param [Sym] type формат возвращаемого результата
+    # @param [DateTime] time исходные время и дата
+    # @param [Sym] what формат возвращаемого результата, принимает одно из следующих значений
     # @option :full форматирует дату и время (по умолчанию)
     # @option :date форматирует только дату
     # @option :time форматирует только время
+    # @param [Sym] type форма в которой возращать результат: длинная ("28 апреля 2015 г. 10:34:52") или короткая ("28/04/2015 10:34")
+    # @option :full длинна форма
+    # @option :short короткая форма
     # @return [String] строка с форматированными датой и временем
+    # @example Примеры использования
+    #   StTools::Setup.setup(:ru)
+    #   StTools::Human.format_time(Time.now, :full, :full)       #=> "30 апреля 2015 г. 08:54:34"
+    #   StTools::Human.format_time(Time.now, :date, :full)       #=> "30 апреля 2015 г."
+    #   StTools::Human.format_time(Time.now, :time, :full)       #=> "08:54:34"
+    #   StTools::Human.format_time(Time.now, :full, :short)      #=> "30/04/2015 08:55"
+    #   StTools::Human.format_time(Time.now, :date, :short)      #=> "30/04/2015"
+    #   StTools::Human.format_time(Time.now, :time, :short)      #=> "08:55"
     def self.format_time(time, what, type)
-      if [:full, :date, :time].include?(what) == false
+      unless [:full, :date, :time].include?(what)
         warn "WARNING: what ':#{what.to_s}' must be in [:full, :date, :time]. Use ':full' now (at line #{__LINE__} of StTools::#{File.basename(__FILE__)})"
         what = :full
       end
       return I18n.l(time, :format => "#{what.to_s}_#{type.to_s}".to_sym)
     end
 
+
+
     private
 
+
+
+
     def self.ago_in_words_pair(secs)
       mins = (secs / 60).to_i
       hours = (mins / 60).to_i

data/lib/st_tools/progress_bar.rb

@@ -1,6 +1,13 @@
 module StTools
   class ProgressBar
-    attr_reader :usage, :progress, :executed_at
+    # Количество вызовов метода progress=.
+    attr_reader :usage
+    # Текущее значение прогресс-бара
+    attr_reader :progress
+    # Время выполнения всей операции в секундах (формируется после достижения max)
+    attr_reader :executed_at
+    # Максимальное значение прогресс-бара
+    attr_reader :max
 
     # Инициализация прогресс-бара
     #
@@ -8,7 +15,8 @@ module StTools
     # @option opts [String] :title заголовок прогресс-бара
     # @option opts [Integer] :max максимальное значение
     # @option opts [Integer] :progress текущее значение (по умолчанию 0)
-    # @option opts [String] :footer резюмирующая строка. Допускает два шаблона: [memory] и [executed_at]
+    # @option opts [String] :footer резюмирующая строка. Допускает два шаблона: [memory] и [executed_at], например:
+    #   "Завершено за [executed_at] секунд. Занятая память [memory]"
     # @option opts [Integer] :step шаг кратно которому реально перерисовывается прогресс-бар
     # @return [Object] нет
     def initialize(opts = {})
@@ -25,7 +33,7 @@ module StTools
       init_progress_bar
     end
 
-    # Функция устанавливает новое значение прогресс-бара
+    # Метод устанавливает новое значение прогресс-бара
     #
     # @param [Integer] val новое значение прогресс-бара. Если равно max - то вызывается функция вывода футера
     # @return [Object] нет
@@ -43,6 +51,7 @@ module StTools
       end
     end
 
+
     private
 
 

data/lib/st_tools/string.rb

@@ -1,10 +1,12 @@
 module StTools
   class String
 
-    # Функция преобразует текст в транслит
+    # Метод преобразует текст в транслит
     #
     # @param [String] text исходная строка с русскими буквами
     # @return [String] строка в транслите
+    # @example Примеры использования
+    #   StTools::String.translit("Жмеринка")   #=> "Zhmerinka"
     def self.translit(text)
       return nil if text.nil?
       translited = text.tr('абвгдеёзийклмнопрстуфхэыь', 'abvgdeezijklmnoprstufhey\'\'')
@@ -18,31 +20,38 @@ module StTools
       return translited
     end
 
-    # Функция с хорошей производительностью преобразует строку в нижний регистр.
-    # Одновременно буква 'ё' замещается на 'е'
+    # Метод преобразует строку в нижний регистр с одновременной заменой буквы 'ё' на 'е'.
+    # Метод имеет примерно в два раза более высокую производительности по сравнению с традиционным .mb_chars.downcase.to_s,
+    # но имеет ограничение - работа только с русскими и английскими строками
     #
     # @param [String] text строка в произвольном регистре
     # @return [String] строка в нижнем регистре
+    # @example Примеры использования
+    #   StTools::String.downcase("Hello, Вася!")   #=> "hello, вася!"
     def self.downcase(text)
       return nil if text.nil?
       return text.tr('QWERTYUIOPASDFGHJKLZXCVBNMАБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯ',
                      'qwertyuiopasdfghjklzxcvbnmабвгдеёжзийклмнопрстуфхцчшщъыьэюя').gsub('ё', 'е')
     end
 
-    # Функция с хорошей производительностью преобразует строку в верхний регистр.
-    # Одновременно буква 'Ё' замещается на 'Е'
+    # Метод преобразует строку в верхний регистр с одновременной заменой буквы 'Ё' на 'Е'.
+    # Метод имеет примерно в два раза более высокую производительности по сравнению с традиционным .mb_chars.downcase.to_s,
+    # но имеет ограничение - работа только с русскими и английскими строками
     #
     # @param [String] text строка в произвольном регистре
-    # @return [String] строка в нижнем регистре
+    # @return [String] строка в верхнем регистре
+    # @example Примеры использования
+    #   StTools::String.upcase("Hello, Вася!")   #=> "HELLO, ВАСЯ!"
     def self.upcase(text)
       return nil if text.nil?
       return text.tr('qwertyuiopasdfghjklzxcvbnmабвгдеёжзийклмнопрстуфхцчшщъыьэюя',
                      'QWERTYUIOPASDFGHJKLZXCVBNMАБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯ').gsub('Ё', 'Е')
     end
 
-    # Функция заменяет в исходной строке символы английские, но похожие
-    # на русские на соответстующие русские. То есть это похоже на ситуацию,
-    # когда Google меняет случайно написанное английскими буквами на русское
+    # Метод заменяет в исходной строке английские символы, похожие
+    # на русские - на соответстующие русские символы. То есть это похоже на ситуацию,
+    # когда Google меняет слово, случайно написанное английскими буквами - на русское слово. Одновременно
+    # буква 'ё' меняется на 'е'.
     #
     # @param [String] text текст со смесью английских и русских букв
     # @return [String] текст только с русскими буквами
@@ -51,28 +60,33 @@ module StTools
       return text.tr('ёЁEeHCcTOoPpAHKXxBM', 'еЕЕеНСсТОоРрАНКХхВМ')
     end
 
-    # Данную функцию рекомендуется вызывать каждый раз, как юзер вводит текст,
-    # для того, чтобы:
-    # - убрать букву 'ё'
-    # - перевести строку в нижний регистр
-    # - заменить случайно введенные английские буквы на русские
-    # - убрать лидирующие и завершающие пробелы
-    # - оставить в строке только один пробел между слов
+    # Метод проводит нормализацию строки для последующей машиной обработки. При этом осуществляется:
+    # - убирается букву 'ё'
+    # - перевод строку в нижний регистр
+    # - замена случайно введенных английских букв на русские
+    # - убираются лидирующие и завершающие пробелы
+    # - в строке удаляются повторные пробелы между словами
     #
     # @param [String] text строка, введенная пользователям
     # @return [String] строка без 'ё', в нижнем регистре, без английских букв
+    # @example Примеры использования
+    #   StTools::String.normalize("  Ёлки-     ПАЛКИ")   #=> "елки- палки"
     def self.normalize(text)
       return nil if text.nil?
       return self.downcase(self.delat(text)).strip.gsub(/\s{1,100}/, ' ')
     end
 
-    # Для целей выдачи информации клиенту в неполном объеме, данная функция позволяет
-    # закрыть часть строки звездочками. При этом число звездочек в строке определеяется
-    # ее длиной. Чем строка дилинее - тем больше в ней звездочек
+    # Метод позволяет показывать клиенту строку в неполном объеме, с закрытием части символов в строке звездочкой.
+    # При этом число звездочек в строке определеяется ее длиной. Чем строка дилинее - тем больше в ней звездочек.
     #
     # @param [String] text строка, которую необходимо закрыть звездочками
     # @return [String] строка, часть символов которой заменена звездочками
-    def self.hide_text(text)
+    # @example Примеры использования
+    #   StTools::String.hide("мы")                          #=> "мы"
+    #   StTools::String.hide("москва")                      #=> "мо*ква"
+    #   StTools::String.hide("длиннаяфраза")                #=> "дли**аяфраза"
+    #   StTools::String.hide("просто произвольная фраза")   #=> "**осто пр*извол*н*я фраза"
+    def self.hide(text)
       return nil if text.nil?
       len = text.length - 3
       0.upto((len/4).to_i) do
@@ -82,7 +96,7 @@ module StTools
       return text
     end
 
-    # Функция аналогична обычной функции split, однако дополнительно может выполнять следующие действия
+    # Метод аналогичен обычной функции split, однако дополнительно может выполнять следующие действия:
     # - strip каждого элемента
     # - normalize соответсвующей функцией (#normalize)
     # - сортировка в прямом порядке
@@ -95,8 +109,13 @@ module StTools
     # @option opts [Boolean] :sort - сортировать выходной массив
     # @option opts [Boolean] :uniq - удалить из массива дубликаты
     # @return [Array] массив элементов из строки
+    # @example Примеры использования
+    #   StTools::String.split("саша, Паша,   ТАНЯ, Алина", ',')                                                 #=> ["саша", "Паша", "ТАНЯ", "Алина"]
+    #   StTools::String.split("саша, Паша,   ТАНЯ, Алина", ',', normalize: true)                                #=> ["саша", "паша", "таня", "алина"]
+    #   StTools::String.split("саша, Паша,   ТАНЯ, Алина", ',', normalize: true, sort: true)                    #=> ["алина", "паша", "саша", "таня"]
+    #   StTools::String.split("саша, Паша,   ТАНЯ, Алина,  таня", ',', normalize: true, sort: true, uniq: true) #=> ["алина", "паша", "саша", "таня"]
     def self.split(text, separator, opts = {})
-      return nil if text.nil?
+      return [] if text.nil?
       out = text.split(separator)
       out.map! { |x| x.strip }
       out.map! { |x| self.normalize(x) } if opts[:normalize]
@@ -108,7 +127,7 @@ module StTools
       return []
     end
 
-    # Функция возвращает полный массив Array [1, 4, 5, 6, 7, 456] для строк вида '1, 4, 5-7, 456'.
+    # Метод возвращает полный массив Array [1, 4, 5, 6, 7, 456] для строк вида '1, 4, 5-7, 456'.
     # Дополнительно осуществляется:
     # - сортировка в прямом порядке
     # - удаление дубликотов
@@ -118,8 +137,12 @@ module StTools
     # @option opts [Boolean] :sort - сортировать выходной массив
     # @option opts [Boolean] :uniq - удалить из массива дубликаты
     # @return [Array] массив чисел
+    # @example Примеры использования
+    #   StTools::String.to_range("1, 4, 5-7, 456, 6")                           #=> [1, 4, 5, 6, 7, 456, 6]
+    #   StTools::String.to_range("1, 4, 5-7, 456, 6", sort: true)               #=> [1, 4, 5, 6, 6, 7, 456]
+    #   StTools::String.to_range("1, 4, 5-7, 456, 6", sort: true, uniq: true)   #=> [1, 4, 5, 6, 7, 456]
     def self.to_range(text, opts = {})
-      return nil if text.nil?
+      return [] if text.nil?
       out = Array.new
 
       tmp = self.split(text, ',')
@@ -138,11 +161,12 @@ module StTools
       return out
     end
 
-    # Функция делает заглавной первую букву в словах, разделенных пробелами или тире.
-    # Подключеие ActiveSupport не требуется
+    # Метод делает заглавной первую букву в словах, разделенных пробелами или дефисом.
     #
     # @param [String] text исходная строка
     # @return [String] строка с первыми заглавными буквами
+    # @example Примеры использования
+    #   StTools::String.caps("саНКТ-петеРБург")    #=> "Санкт-Петербург"
     def self.caps(text)
       return nil if text.nil?
       str = self.downcase(text).split(/[\-\s]/).map { |x| self.upcase(x[0]) + x[1,x.length] }
@@ -156,13 +180,24 @@ module StTools
       return text
     end
 
-    # Функция формирует boolean значение из строки
+    # Метод конвертирует строку в тип boolean
     #
     # @param [String] text исходная строка, содержащая 'true/false', 'on/off', '1/0'
     # @return [Boolean] true или false
+    # @example Примеры использования
+    #   StTools::String.to_bool("True")    #=> true
+    #   StTools::String.to_bool("trUE")    #=> true
+    #   StTools::String.to_bool("on")      #=> true
+    #   StTools::String.to_bool("1")       #=> true
+    #   StTools::String.to_bool("Да")      #=> true
+    #   StTools::String.to_bool("Yes")     #=> true
+    #   StTools::String.to_bool("false")   #=> false
+    #   StTools::String.to_bool("fALse")   #=> false
+    #   StTools::String.to_bool("oFF")     #=> false
+    #   StTools::String.to_bool("0")       #=> false
     def self.to_bool(text)
       return false if text.nil?
-      return true if ['true', 'on', '1'].include?(self.downcase(text.to_s))
+      return true if ['true', 'on', '1', 'да', 'yes'].include?(self.downcase(text.to_s))
       false
     end
 

data/lib/st_tools/system.rb

@@ -1,11 +1,14 @@
 module StTools
   class System
 
+    # Метод возвращает размер памяти, занятой приложением
+    #
+    # @return [Integer] размер памяти в байтах
     def self.memory
       return `ps -o rss -p #{Process::pid}`.chomp.split("\n").last.strip.to_i
     end
 
-    # Возвращает размер терминала - число строк в терминале или число символов в строке
+    # Метод возвращает размер терминала - число строк в терминале или число символов в строке
     #
     # @param [Sym] size возвращаемый параметр
     # @option size [Sym] :width вернуть число символов в строке терминала

data/lib/st_tools/version.rb

@@ -1,3 +1,3 @@
 module StTools
-  VERSION = '0.3.2'
+  VERSION = '0.3.3'
 end

data/lib/st_tools.rb

@@ -19,10 +19,18 @@ module StTools
 
   class Setup
 
+    # Метод загрузки файлов локализации для методов форматирования времени. Принимает значения [:en, :ru]
+    #
+    # @param [Object] locale - язык локализации, поддерживается :ru, :en. Если передена неизвестная локализация
+    #   по умолчанию будет использована :ru
+    # @return [Object] нет
     def self.setup(locale)
+      locale = :ru unless [:ru, :en].include?(locale)
       self.setup_locale(locale)
     end
 
+    private
+
     def self.setup_locale(locale)
       require 'i18n'
       ::I18n.load_path += Dir[File.dirname(File.expand_path(__FILE__)) + '/i18n/**/*.yml']

data/test/string_lib_spec.rb

@@ -39,7 +39,7 @@ describe 'Проверка методов StTools::String.*' do
   end
 
   it '.hide_text' do
-    test = ::StTools::String.hide_text('Ярослав    Му(y)дрёный')
+    test = ::StTools::String.hide('Ярослав    Му(y)дрёный')
     expect(test).to include('*')
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: st_tools
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Stan Zhuravlev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-04-29 00:00:00.000000000 Z
+date: 2015-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,11 +67,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |-
-  Библиотека содержит функции, реализующие:
-  - преобразование строк с учетом русского языка
-  - формирования человеко-удобной информации
-  - получения разных системных характеристик CLI-приложений
-  - управление прогресс-баром CLI-приложений
+  Библиотека StTools предназначена для поддержки CLI- и Rails-приложений. Она обеспечивает
+  различное преобразование строк с учетом русского языка, формирование человеко-удобного представления времени и чисел,
+  получения разных системных характеристик CLI-приложений (память, размер экрана терминала),
+  управление прогресс-баром CLI-приложений.
 email:
 - stan@post-api.ru
 executables: []
@@ -113,9 +112,9 @@ require_paths:
 - lib/st_tools
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="