st_tools 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dbc4df1cb453510d365fd64c9706ff8f6a733412
+  data.tar.gz: 999050e842607f77143e00d9881174f8489a30d8
+SHA512:
+  metadata.gz: 2f46739ed694b711f20045b4e82f5d0bdfd0cfd8e504d45bf875dac97743e7f6dd9cfabae93080a6b7b41e54384fd0daeba74cb065f2272cbdbac38343f4f07e
+  data.tar.gz: ecf50eaa21dd3672fe40d0e42a4905619ea944bc4996d58c0a949391b6f9f6cafb050a6e880136e3656663bb732368eb5d0b5fd9cbddfd79f3e3778e4abacdcb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Stan Zhuravlev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,258 @@
+# StTools
+
+Данные гем содержит методы, обеспечивающие:
+- преобразование строк с учетом русского языка
+- формирования человеко-удобной информации
+- получения разных системных характеристик CLI-приложений
+- управление прогресс-баром CLI-приложений
+
+## Установка
+
+Добавить в Gemfile:
+
+```ruby
+gem 'st_tools'
+```
+
+Установите гем cредствами Bundler:
+
+    $ bundle
+
+Или установите его отдельно:
+
+    $ gem install st_tools
+
+# Зависимости
+
+Для работы гема требуется Ruby не младше версии 2.0.0. StTools не привязана к Rails и может использоваться в CLI-приложениях.
+ Класс StTools::ProgressBar является надстройкой над гемом 'progressbar-ruby'.
+
+## Использование
+
+Часть методов библиотеки поддерживают русскую и английскую локализацию.
+Поскольку все методы StTools могут вызываться без создания класса - конструктор не вызывается.
+Поэтому перед работой библиотеки рекомендуется вызвать StTools::Setup.setup(:ru или :en).
+
+### StTools::Human
+
+Вы вызываете в любой момент StTools::Human.memory и узнаете текущий размер памяти, занимаемый приложением (процессом)
+
+```ruby
+StTools.Human.memory               # => 14 кбайт
+StTools.Human.memory               # => 45,3 Мбайт
+StTools.Human.memory               # => 2,6 Гбайт
+```
+
+Вы вызываете StTools::Human.bytes и перевести любое значение в человеко-удобный вид. Метод можно использовать для показа размера файла
+
+```ruby
+StTools.Human.bytes(345)           # => 345 байт
+StTools.Human.bytes(14653)         # => 14,5 кбайт
+StTools.Human.bytes(23653763)      # => 23,4 Мбайт
+```
+
+Вы вызываете StTools::Human.number для перевода любого значения в человеко-удобный вид.
+Метод можно использовать для показа, например, суммы денег
+
+```ruby
+StTools.Human.number(345)           # => 345
+StTools.Human.number(14653)         # => 14,6 тыс.
+StTools.Human.number(23653763)      # => 23,7 млн.
+```
+
+Вы имеете возможность узнать разницу между текущим временем и временем какого-либо события.
+
+```ruby
+StTools::Setup.setup(:ru)
+StTools.Human.ago_in_words(DateTime.new(2014,12,31), true)        # => 4 месяца 21 день назад
+StTools.Human.ago_in_words(DateTime.new(2013,08,01), false)       # => 1 год 8 месяца
+StTools.Human.ago_in_words(Time.now - 15, true)                   # => 15 секунд назад
+```
+
+```ruby
+StTools::Setup.setup(:en)
+StTools.Human.ago_in_words(DateTime.new(2014,12,31), true)        # => 4 months 21 days ago
+StTools.Human.ago_in_words(DateTime.new(2013,08,01), false)       # => 1 year 8 months
+StTools.Human.ago_in_words(Time.now - 15, true)                   # => 15 seconds ago
+```
+
+Устанавливая флаг ```ago=true```, метод добавит слово "назад" или "ago" в конце фразы.
+
+Результирующая фраза всегда состоит из одного показатели (при разнице времени событий меньше минуты) или из двух (минуты/секунды, часы/минуты, дни/часы, месяцы/дни, года/месяцы)
+
+Вы имеете форматировать дату и время в соответствии с правилами русского и английского языка.
+
+```ruby
+StTools::Setup.setup(:ru)
+StTools.Human.format_time(Time.now, :full, :full)              # => 28 апреля 2015 г. 10:45:23
+StTools.Human.format_time(Time.now, :date, :full)              # => 28 апреля 2015 г.
+StTools.Human.format_time(Time.now, :time, :full)              # => 10:45:23
+StTools.Human.format_time(Time.now, :full, :short)             # => 28/04/2015 10:45
+StTools.Human.format_time(Time.now, :date, :short)             # => 28/04/2015
+StTools.Human.format_time(Time.now, :time, :short)             # => 10:45
+```
+
+```ruby
+StTools::Setup.setup(:en)
+StTools.Human.format_time(Time.now, :full, :full)              # => April 28, 2015 09:45:23 am
+StTools.Human.format_time(Time.now, :date, :full)              # => April 28, 2015
+StTools.Human.format_time(Time.now, :time, :full)              # => 09:45:23 am
+StTools.Human.format_time(Time.now, :full, :short)             # => 04/28/2015 09:45 am
+StTools.Human.format_time(Time.now, :date, :short)             # => 04/28/2015
+StTools.Human.format_time(Time.now, :time, :short)             # => 09:45 am
+```
+
+Вы можете подмешать модуль `StTools::Module` в классы String, Integer, Time.
+
+```ruby
+StTools::Setup.setup(:ru)
+
+class String
+   extend StTools::Module::String
+end
+
+(Time.now - 15).human_ago                         # => 15 секунд назад
+Time.now.format_date                              # => 28 апреля 2015 г.
+Time.now.format_date(:short)                      # => 28/04/2015
+```
+
+### StTools::String
+
+Транслитерация строки из русского на английский
+
+```ruby
+StTools::String.translit('Жмеринка')                  # => Zhmerinka
+```
+
+Иногда пользователи вводят английские буквы, похожие на русские, чаще все - букву 'C'. Метод delat заменяет такие символы на русские
+
+```ruby
+StTools::String.delat('Соль')                         # => Соль
+```
+
+Перевести строку в верхний или нижний регистр. Используется метод, альтернативный mb_chars (примерно в два раза производительней)
+
+```ruby
+StTools::String.downcase('Москва')                    # => москва
+StTools::String.upcase('Москва')                      # => МОСКВА
+```
+
+Иногда надо нормализовать строку и привести ее к виду, удобному для машинной обработки.
+Метод normalize последовательно делает: strip, delat, downcase
+
+```ruby
+StTools::String.normalize('   Москва  ')              # => "москва"
+```
+
+Следующий метод приводит строку к нижнему регистру, но делает первую букву заглавной.
+Удобно для нормализации имени и фамилии, вводимых пользователем
+
+```ruby
+StTools::String.caps('санКТ-петерБург')              # => "Санкт-Петербург"
+```
+
+Для реализации деморежимов различных приложений иногда надо скрыть реальный результат.
+Для это можно использовать метод hide_text
+
+```ruby
+StTools::String.hide_text('Краснодар')              # => "Кра*но*ар"
+```
+
+В 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
+```
+
+Если пользователь введет в качестве входного параметра перечисление, следующий метод разобъет его на токены,
+с нормализацией при необходимости
+
+```ruby
+StTools::String.split('ТАНЯ, маша, петя', ',')                                 # => ['ТАНЯ', 'маша', 'петя']
+StTools::String.split('ТАНЯ, маша, петя', ',', normalize: true)                # => ['таня', 'маша', 'петя']
+StTools::String.split('ТАНЯ, маша, петя', ',', normalize: true, sort: true)    # => ['маша', 'петя', 'таня']
+```
+
+Если от пользователя требуется ввести численные значения в виде перечисления или диапазоне, нужно использовать
+метод to_range
+
+```ruby
+StTools::String.to_range('54, 3-6, 5, 1')                                 # => [54, 3, 5, 6, 5, 1]
+StTools::String.to_range('54, 3-6, 5, 1', uniq: true)                     # => [54, 3, 5, 6, 1]
+StTools::String.to_range('54, 3-6, 5, 1', uniq: true, sort: true)         # => [1, 3, 5, 6, 54]
+```
+
+Вы можете подмешать модуль `StTools::Module` в классы String, Integer, Time.
+
+```ruby
+StTools::Setup.setup(:ru)
+
+class String
+   extend StTools::Module::String
+end
+
+'санКТ-петерБург'.caps                         # => Санкт-Петербург
+'санКТ-петерБург'.downcase                     # => санкт-петербург
+'санКТ-петерБург'.upcase                       # => САНКТ-ПЕТЕРБУРГ
+'on'.to_bool                                   # => true
+'34, 2-5, 8, 1'.to_range(sort: true)           # => [1, 2, 4, 5, 8, 34]
+'Краснодар'.hide                               # => Кра*но*ар
+```
+
+### StTools::System
+
+Узнать объем оперативной памяти, занятый приложением
+
+```ruby
+StTools::System.memory                                 # => 145734
+```
+
+Узнать ширину и высоту текущего окна терминала в CLI-режиме
+
+```ruby
+StTools::System.screen(:width)               # => 114
+StTools::System.screen(:height)              # => 25
+```
+
+### StTools::ProgressBar
+
+Данная бибилиотека базируется на геме 'progressbar-ruby' (https://github.com/jfelchner/ruby-progressbar), но надстройка над ним
+упрощает использование библиотеки, и исключает некоторые проблемы.
+
+Библиотека содержит две функции. Первая - инициирует начало отображения прогресс-бара
+
+```ruby
+@bar = ::StTools::ProgressBar.new(title: "Тестовый запуск",
+                                  footer: "Занято [memory], выполнено за [executed_at] сек.",
+                                  max: 10000000)
+```
+
+Задается заголовок, который будет отображен перед прогресс-баром. Затем указывается футер, который отобразиться как
+только прогресс станет 100%. Футер содержит две шаблона:
+- [memory], который будет заменен на результат вызова StTools::Human.memory
+- [executed_at], который будет заменен на время в секундах завершенного процесса
+
+Значение :max содержит финальное значение прогресса. Дополнительно рекомендуется задать значение :step, которое
+показывает, на каком шаге в реальности должен меняться процент выполнения операции.
+
+Затем, в цикле, который обеспечивает выполнение длительной операции, необходимо менять значение progress.
+
+```ruby
+10000010.times do |val|
+  @bar.progress = val
+end
+```
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/st_tools/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "st_tools"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+gem install st_tools --rdoc
+
+
+# Do any other automated setup that you need to do here

data/lib/i18n/en.yml

@@ -0,0 +1,72 @@
+# Files in the config/locales directory are used for internationalization
+# and are automatically loaded by Rails. If you want to use locales other
+# than English, add the necessary files in this directory.
+#
+# To use the locales, use `I18n.t`:
+#
+#     I18n.t 'hello'
+#
+# In views, this is aliased to just `t`:
+#
+#     <%= t('hello') %>
+#
+# To use a different locale, set it with `I18n.locale`:
+#
+#     I18n.locale = :es
+#
+# This would use the information in config/locales/es.yml.
+#
+# To learn more, please read the Rails Internationalization guide
+# available at http://guides.rubyonrails.org/i18n.html.
+
+en:
+  hello: "Hello world"
+
+  defaults: &defaults
+    month_names:
+      [~, January, February, March, April, May, June, July, August, September, October, November, December]
+    formats:
+      default: "%m/%d/%Y"
+      date_full: "%B %-d, %Y"
+      full_full: "%B %-d, %Y %I:%M:%S %P"
+      time_full: "%I:%M:%S %P"
+      date_short: "%m/%d/%Y"
+      full_short: "%m/%d/%Y %I:%M:%S %P"
+      time_short: "%I:%M %P"
+  date:
+    <<: *defaults
+  time:
+    <<: *defaults
+    pm: pm
+    am: am
+
+
+  common:
+    ago:
+      very_long: 'long, long ago'
+      just_now: 'just now'
+      ago_word: 'ago'
+      year:
+        one: year
+        two: years
+        other: years
+      month:
+        one: month
+        two: months
+        other: months
+      day:
+        one: day
+        two: days
+        other: days
+      hour:
+        one: hour
+        two: hours
+        other: hours
+      minute:
+        one: minute
+        two: minutes
+        other: minutes
+      second:
+        one: second
+        two: seconds
+        other: seconds

data/lib/i18n/ru.yml

@@ -0,0 +1,49 @@
+ru:
+  hello: "Привет, мир!"
+
+  defaults: &defaults
+    month_names:
+      [~, января, февраля, марта, апреля, мая, июня, июля, августа, сентября, октября, ноября, декабря]
+    formats:
+       default: "%d/%m/%Y"
+       date_full: "%-d %B %Y г."
+       full_full: "%-d %B %Y г. %H:%M:%S"
+       time_full: "%H:%M:%S"
+       date_short: "%d/%m/%Y"
+       full_short: "%d/%m/%Y %H:%M"
+       time_short: "%H:%M"
+  date:
+    <<: *defaults
+  time:
+    <<: *defaults
+
+
+  common:
+    ago:
+      very_long: 'очень давно'
+      just_now: 'сейчас'
+      ago_word: 'назад'
+      year:
+        one: год
+        two: года
+        other: лет
+      month:
+        one: месяц
+        two: месяца
+        other: месяцев
+      day:
+        one: день
+        two: дня
+        other: дней
+      hour:
+        one: час
+        two: часа
+        other: часов
+      minute:
+        one: минута
+        two: минуты
+        other: минут
+      second:
+        one: секунда
+        two: секунды
+        other: секунд

data/lib/modules/fias.rb

@@ -0,0 +1,57 @@
+module StTools
+  module Module
+    module Fias
+
+      # Определяет принадлежность aoguid к федеральным городам (Москва, Санкт-Питербург, Байконур, Севастополь)
+      #
+      # @return [Boolean] true, если объект имеет тип uuid и равен aoguid одного из
+      #   четырех федеральных городов
+      def federal?
+        ::StTools::Fias.federal?(self)
+      end
+
+      # Определяет, является ли aoguid Москвой
+      #
+      # @return [Boolean] true, если объект имеет тип uuid и равен aoguid Москвы
+      def moscow?
+        ::StTools::Fias.moscow?(self)
+      end
+
+      # Определяет, является ли aoguid Санкт-Петербургом
+      #
+      # @return [Boolean] true, если объект имеет тип uuid и равен aoguid Санкт-Петербурга
+      def spb?
+        ::StTools::Fias.spb?(self)
+      end
+
+      # Определяет, является ли aoguid Севастополем
+      #
+      # @return [Boolean] true, если объект имеет тип uuid и равен aoguid Севастополя
+      def sevastopol?
+        ::StTools::Fias.sevastopol?(self)
+      end
+
+      # Определяет, является ли aoguid Байконуром
+      #
+      # @return [Boolean] true, если объект имеет тип uuid и равен aoguid Байконура
+      def baikonur?
+        ::StTools::Fias.baikonur?(self)
+      end
+
+      # Определяет, содержит ли строка идентификатор типа uuid
+      #
+      # @return [Boolean] true, если строка имеет формат uuid
+      def uuid?
+        ::StTools::Fias.uuid?(self)
+      end
+
+      # Определяет, содержит ли строка почтовый индекс
+      #
+      # @return [Boolean] true, если строка имеет 6 цифр
+      def postalcode?
+        ::StTools::Fias.postalcode?(self)
+      end
+
+    end
+  end
+end

data/lib/modules/integer.rb

@@ -0,0 +1,28 @@
+module StTools
+  module Module
+    module Integer
+
+      # Переводит число в строку с размером в байтах, кбайтах, Мбайтах и пр.
+      #
+      # @return [String] строка с суффиксом
+      def human_number
+        ::StTools::Human.number(self)
+      end
+
+      # Переводит число в строку с размером в байтах, кбайтах, Мбайтах и пр.
+      #
+      # @return [String] строка с суффиксом
+      def human_bytes
+        ::StTools::Human.bytes(self)
+      end
+
+      # Переводит число в значение boolean (true или false). Любое число false кроме 1 (единицы)
+      #
+      # @return [Boolean] true или false
+      def to_bool
+        ::StTools::String.to_bool(self)
+      end
+
+    end
+  end
+end

data/lib/modules/string.rb

@@ -0,0 +1,105 @@
+module StTools
+  module Module
+    module String
+
+      # Метод проводит транслитерацию русского текста
+      #
+      # @return [String] транслитерированная строка
+      def translit
+        ::StTools::String.translit(self)
+      end
+
+      # Метод заменяет случайно набранные английские символы (с, р, y) в соответствующие по написанию русские
+      #
+      # @return [String] строка, в которой случайно набранные английские символы заменены на русские
+      def delat
+        ::StTools::String.delat(self)
+      end
+
+      # Метод переводит русскую и английскую строку в нижний регистр без
+      # использования MultiByte (только UTF-8)
+      #
+      # @return [String] строка в нижнем регистре
+      # @example Перевод строки в нижний регистр
+      #   "Владимир".upcase #=> "владимир"
+      def downcase
+        ::StTools::String.downcase(self)
+      end
+
+      # Метод переводит русскую и английскую строку в верхний регистр без
+      # использования MultiByte (только UTF-8)
+      #
+      # @return [String] строка в верхнем регистре
+      # @example Перевод строки в верхний регистр
+      #   "Владимир".upcase #=> "ВЛАДИМИР"
+      def upcase
+        ::StTools::String.upcase(self)
+      end
+
+      # Метод удаляет пробелы в начале и конце строки, проводит #delat, #downcase
+      #
+      # @return [String] нормализованная строка
+      # @example Нормализация строки
+      #   "   Владимир".normalize #=> "владимир"
+      def normalize
+        ::StTools::String.normalize(self)
+      end
+
+      # Метод заменяет часть символов строки на звездочки
+      #
+      # @return [String] строка, в которой часть букв заменены на звездочки (случайным образом)
+      # @example Сокрытие части строки
+      #   "Владимир".hide #=> "Вл*ди*ир"
+      def hide
+        ::StTools::String.hide_text(self)
+      end
+
+      # Метод разделяет строку на подстроки, и нормализует кажду подстроку через #normalize
+      #
+      # @param [String] separator строка-разделитель
+      # @param [Hash] opts - массив параметров вызова метода
+      # @option opts [Boolean] :sort - сортировать результирующий массив
+      # @option opts [Boolean] :uniq - удалить из результирующего массива дубликаты
+      # @return [Array] массив чисел
+      # @example Преобразование строки в массив чисел
+      #   "Москва , Питер , Владимир".split(",") #=> ['москва', 'питер', 'владимир']
+      def split(separator, opts = {})
+        ::StTools::String.split(self, separator, opts)
+      end
+
+      # Метод переводит введенные человеком цифры, перечисленные через запятую и тире
+      # в массив чисел
+      #
+      # @param [Hash] opts
+      # @option opts [Boolean] :sort - сортировать результирующий массив
+      # @option opts [Boolean] :uniq - удалить из результирующего массива дубликаты
+      # @return [Array] массив чисел
+      # @example Преобразование строки в массив чисел
+      #   "6, 3, 8-10, 1".to_range #=> [6, 3, 8, 9, 10, 1]
+      #   "6, 3, 8-10".to_range(sort: true) #=> [1, 3, 6, 8, 9, 10]
+      def to_range(opts = {})
+        ::StTools::String.to_range(self, opts)
+      end
+
+      # Метод делает строку downcase но каждую букву каждого слова - заглавной
+      #
+      # @return [String] преобразованная строка
+      # @example Капитализация первых букв строки
+      #   "саН-франЦИСКО".caps #=> "Сан-Франциско"
+      def caps
+        ::StTools::String.caps(self)
+      end
+
+      # Метод переводит строку в значение boolean (true или false). True - если строка имеет одно из трех значений:
+      # ['true', 'on', '1']
+      #
+      # @return [Boolean] true или false
+      # @example проверка, что строка - true
+      #   "True".to_bool #=> true
+      def to_bool
+        ::StTools::String.to_bool(self)
+      end
+
+    end
+  end
+end

data/lib/modules/time.rb

@@ -0,0 +1,23 @@
+module StTools
+  module Module
+    module Time
+
+      def human_date(type = :full)
+        ::StTools::Human.format_time(self, :date, type)
+      end
+
+      def human_time(type = :full)
+        ::StTools::Human.format_time(self, :time, type)
+      end
+
+      def human_datetime(type = :full)
+        ::StTools::Human.format_time(self, :full, type)
+      end
+
+      def human_ago(ago = true)
+        ::StTools::Human.ago_in_words(self, ago)
+      end
+
+    end
+  end
+end