sanscript 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d1e473866926c96b58966e9a570d1310ae9d8eff
-  data.tar.gz: b6f0165d110775e8f4adb49de170634638afb372
+  metadata.gz: 86f56c7a86cc995ae43b8ccd595937d9199ba620
+  data.tar.gz: 319cabddf6e0f49f35ab0e9f7d20dcb5005865da
 SHA512:
-  metadata.gz: 6abff0d8586ff49952c7a308d4ddaf142fcc0ae4be41a739ed287a5705b2bca2cf104ef965c37cdc39dd6b0ce34155d2509722275494a87125e8c5b65403f062
-  data.tar.gz: d66c8bfd4cd7faddf4e544e5287e7c83a8c7d855741aac71f2153f457e4e275a47981cff9559009d7d7ce7cc0b7c3faf20c684d11cf1561f09c6924b500f4e73
+  metadata.gz: c874822cef8dc80268b660adbb555ea05c06c2c18d8a57b0c0e3a20e68e7af1dff1f3d1c9570d2987cb7b416f56ee0e9045dc39f0c6fc0fb8f1dab866f342a61
+  data.tar.gz: 64e1f0ca20f1de06eb0eff45323e53f20f8a99a1d21edfcaaf210899ceb03d9ea54b94ac66ceebc80c059a771e01ea6118f478ee70fcd88588281d2e2889835b

data/lib/sanscript.rb

@@ -4,26 +4,41 @@ require "sanscript/detect"
 require "sanscript/transliterate"
 require "sanscript/benchmark"
 
+# Sanscript.rb detection/transliteration module for Sanskrit.
 module Sanscript
   module_function
 
-  # Proxies the Detect.detect_script method
+  # Attempts to detect the encoding scheme of the provided string.
+  # Simple proxy for {Detect.detect_scheme}
   #
+  # @param text [String] a string of Sanskrit text
+  # @return [Symbol, nil] the Symbol of the scheme, or nil if no match
   def detect(text)
-    Detect.detect_script(text)
+    Detect.detect_scheme(text)
   end
 
-  # The transliterate method accepts multiple signatures
-  #   .transliterate(text, to) will auto-detect the source script
-  #   .transliterate(text, to, from) will specify the source and target script
+  # Transliterates a string, optionally detecting its source-scheme first.
   #
-  #   Final Hash arguments are passed along as options.
+  # @overload transliterate(text, from, to, **opts)
+  #   @param text [String] the String to transliterate
+  #   @param from [Symbol] the name of the scheme to transliterate from
+  #   @param to [Symbol] the name of the scheme to transliterate to
+  #   @option opts [Boolean] :skip_sgml (false) escape SGML-style tags in text string
+  #   @option opts [Boolean] :syncope (false) activate Hindi-style schwa syncope
+  #   @return [String] the transliterated String
   #
-  def transliterate(text, first, second = nil, **options)
-    if second.nil?
-      second = first
-      first = Detect.detect_script(text)
+  # @overload transliterate(text, to, **opts)
+  #   @param text [String] the String to transliterate
+  #   @param to [Symbol] the name of the scheme to transliterate to
+  #   @option opts [Symbol] :default_scheme a default scheme to fall-back to if detection fails
+  #   @option opts [Boolean] :skip_sgml (false) escape SGML-style tags in text string
+  #   @option opts [Boolean] :syncope (false) activate Hindi-style schwa syncope
+  #   @return [String, nil] the transliterated String, or nil if detection and fallback fail
+  def transliterate(text, from, to = nil, **opts)
+    if to.nil?
+      to = from
+      from = Detect.detect_scheme(text) || opts[:default_scheme] || return
     end
-    Transliterate.transliterate(text, first, second, options)
+    Transliterate.transliterate(text, from, to, opts)
   end
 end

data/lib/sanscript/benchmark.rb

@@ -13,9 +13,11 @@ end
 
 module Sanscript
   using Refinements
+  # Benchmark/testing module.
   module Benchmark
     module_function
 
+    # Runs benchmark-ips test on detection methods.
     def detect!
       iast_string = "nānāśāstrasubhāṣitāmṛtarasaiḥ śrotrotsavaṃ kurvatāṃ yeṣāṃ yānti dināni paṇḍitajanavyāyāmakhinnātmanām teṣāṃ janma ca jīvitaṃ ca sukṛtaṃ tair eva bhūr bhūṣitā śeṣaih kiṃ paśuvad vivekarahitair bhūbhārabhūtair naraḥ"
       deva_string = "नानाशास्त्रसुभाषितामृतरसैः श्रोत्रोत्सवं कुर्वतां येषां यान्ति दिनानि पण्डितजनव्यायामखिन्नात्मनाम् तेषां जन्म च जीवितं च सुकृतं तैर् एव भूर् भूषिता शेषैह् किं पशुवद् विवेकरहितैर् भूभारभूतैर् नरः"
@@ -26,25 +28,26 @@ module Sanscript
       ::Benchmark.ips do |x|
         x.config(time: 5, warmup: 1)
         x.report("Detect Devanagari") do
-          Sanscript::Detect.detect_script(deva_string) == :devanagari
+          raise unless Sanscript::Detect.detect_scheme(deva_string) == :devanagari
         end
         x.report("Detect Malayalam") do
-          Sanscript::Detect.detect_script(malayalam_string) == :malayalam
+          raise unless Sanscript::Detect.detect_scheme(malayalam_string) == :malayalam
         end
         x.report("Detect IAST") do
-          Sanscript::Detect.detect_script(iast_string) == :iast
+          raise unless Sanscript::Detect.detect_scheme(iast_string) == :iast
         end
         x.report("Detect SLP1") do
-          Sanscript::Detect.detect_script(slp1_string) == :slp1
+          raise unless Sanscript::Detect.detect_scheme(slp1_string) == :slp1
         end
         x.report("Detect HK") do
-          Sanscript::Detect.detect_script(hk_string) == :hk
+          raise unless Sanscript::Detect.detect_scheme(hk_string) == :hk
         end
         x.compare!
       end
       true
     end
 
+    # Runs benchmark-ips test on transliteration methods.
     def transliterate!
       iast_string = "nānāśāstrasubhāṣitāmṛtarasaiḥ śrotrotsavaṃ kurvatāṃ yeṣāṃ yānti dināni paṇḍitajanavyāyāmakhinnātmanām teṣāṃ janma ca jīvitaṃ ca sukṛtaṃ tair eva bhūr bhūṣitā śeṣaih kiṃ paśuvad vivekarahitair bhūbhārabhūtair naraḥ"
       deva_string = "नानाशास्त्रसुभाषितामृतरसैः श्रोत्रोत्सवं कुर्वतां येषां यान्ति दिनानि पण्डितजनव्यायामखिन्नात्मनाम् तेषां जन्म च जीवितं च सुकृतं तैर् एव भूर् भूषिता शेषैह् किं पशुवद् विवेकरहितैर् भूभारभूतैर् नरः"
@@ -54,22 +57,22 @@ module Sanscript
         x.config(time: 5, warmup: 2)
 
         x.report("IAST==>Devanagari") do
-          Sanscript.transliterate(iast_string, :iast, :devanagari) == deva_string
+          raise unless Sanscript.transliterate(iast_string, :iast, :devanagari) == deva_string
         end
         x.report("IAST==>SLP1") do
-          Sanscript.transliterate(iast_string, :iast, :slp1) == slp1_string
+          raise unless Sanscript.transliterate(iast_string, :iast, :slp1) == slp1_string
         end
         x.report("SLP1==>Devanagari") do
-          Sanscript.transliterate(slp1_string, :slp1, :devanagari) == deva_string
+          raise unless Sanscript.transliterate(slp1_string, :slp1, :devanagari) == deva_string
         end
         x.report("SLP1==>IAST") do
-          Sanscript.transliterate(slp1_string, :slp1, :iast) == iast_string
+          raise unless Sanscript.transliterate(slp1_string, :slp1, :iast) == iast_string
         end
         x.report("Devanagari==>SLP1") do
-          Sanscript.transliterate(deva_string, :devanagari, :slp1) == slp1_string
+          raise unless Sanscript.transliterate(deva_string, :devanagari, :slp1) == slp1_string
         end
         x.report("Devanagari==>IAST") do
-          Sanscript.transliterate(deva_string, :devanagari, :iast) == iast_string
+          raise unless Sanscript.transliterate(deva_string, :devanagari, :iast) == iast_string
         end
         x.compare!
       end

data/lib/sanscript/detect.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
-# rubocop:disable Style/CaseEquality
 
-#
-# Developed from code available @ https://github.com/sanskrit/detect.js
-#
 module Sanscript
+  # Transliteration scheme detection module.
+  # Developed from code available @ https://github.com/sanskrit/detect.js
   module Detect
+    # rubocop:disable Style/CaseEquality
+
     # Match any character in the block of Brahmic scripts
     # between Devanagari and Malayalam.
     RE_BRAHMIC_RANGE = /[\u0900-\u0d7f]/
@@ -53,7 +53,11 @@ module Sanscript
 
     module_function
 
-    def detect_script(text)
+    # Attempts to detect the encoding scheme of the provided string.
+    #
+    # @param text [String] a string of Sanskrit text
+    # @return [Symbol, nil] the Symbol of the scheme, or nil if no match
+    def detect_scheme(text)
       text = text.to_str.gsub(RE_CONTROL_BLOCK, "")
 
       # Brahmic schemes are all within a specific range of code points.
@@ -77,14 +81,13 @@ module Sanscript
         :itrans
       elsif RE_HARVARD_KYOTO === text
         :hk
-      else
-        :unknown
       end
     end
 
-    # If Ruby 2.4's Regexp#match? method is found, use it for performance
+    # If Ruby 2.4's Regexp#match? method is found, use this version of detect_scheme
     if Regexp.method_defined?(:match?)
-      def detect_script(text)
+      # @!visibility private
+      def detect_scheme(text)
         text = text.to_str.gsub(RE_CONTROL_BLOCK, "")
 
         # Brahmic schemes are all within a specific range of code points.
@@ -108,8 +111,6 @@ module Sanscript
           :itrans
         elsif RE_HARVARD_KYOTO.match?(text)
           :hk
-        else
-          :unknown
         end
       end
     end

data/lib/sanscript/refinements.rb

@@ -2,6 +2,7 @@
 require "ice_nine"
 
 module Sanscript
+  # A set of helpful refinements for duplication and deep freezing.
   module Refinements
     refine Object do
       def deep_dup

data/lib/sanscript/transliterate.rb

@@ -2,20 +2,31 @@
 
 require "sanscript/refinements"
 require "sanscript/transliterate/schemes"
-#
-# Sanscript
-#
-# Sanscript is a Sanskrit transliteration library. Currently, it supports
-# other Indian languages only incidentally.
-#
-# Released under the MIT and GPL Licenses.
-#
 module Sanscript
   using Refinements
+  # Sanskrit transliteration module.
+  # Derived from Sanscript, released under the MIT and GPL Licenses.
+  # "Sanscript is a Sanskrit transliteration library. Currently, it supports
+  # other Indian languages only incidentally."
   module Transliterate
     class << self
-      attr_reader :defaults, :schemes, :scheme_names, :brahmic_schemes, :roman_schemes,
-                  :all_alternates
+      # @return [Array<Symbol>] the names of all supported schemes
+      attr_reader :scheme_names
+
+      # @return [Array<Symbol>] the names of all Brahmic schemes
+      attr_reader :brahmic_schemes
+
+      # @return [Array<Symbol>] the names of all roman schemes
+      attr_reader :roman_schemes
+
+      # @return [Hash] the data for all schemes
+      attr_reader :schemes
+
+      # @return [Hash] the alternate-character data for all schemes
+      attr_reader :all_alternates
+
+      # @return [Hash] the default transliteration options
+      attr_reader :defaults
     end
 
     @defaults = {
@@ -27,44 +38,37 @@ module Sanscript
 
     module_function
 
+    # Check whether the given scheme encodes Brahmic Sanskrit.
     #
-    #  Check whether the given scheme encodes Brahmic Sanskrit.
-    #
-    #  @param name  the scheme name
-    #  @return      boolean
-    #
+    # @param name [Symbol] the scheme name
+    # @return [Boolean]
     def brahmic_scheme?(name)
       @brahmic_schemes.include?(name.to_sym)
     end
 
-    #
     #  Check whether the given scheme encodes romanized Sanskrit.
     #
-    #  @param name  the scheme name
-    #  @return      boolean
-    #
+    #  @param name [Symbol] the scheme name
+    #  @return [Boolean]
     def roman_scheme?(name)
       @roman_schemes.include?(name.to_sym)
     end
 
-    #
     # Add a Brahmic scheme to Sanscript.
     #
     # Schemes are of two types: "Brahmic" and "roman". Brahmic consonants
     # have an inherent vowel sound, but roman consonants do not. This is the
     # main difference between these two types of scheme.
     #
-    # A scheme definition is an object ("{}") that maps a group name to a
-    # list of characters. For illustration, see the "devanagari" scheme at
-    # the top of this file.
+    # A scheme definition is a Hash that maps a group name to a
+    # list of characters. For illustration, see `transliterate/schemes.rb`.
     #
     # You can use whatever group names you like, but for the best results,
     # you should use the same group names that Sanscript does.
     #
-    # @param name    the scheme name
-    # @param scheme  the scheme data itself. This should be constructed as
-    #                described above.
-    #
+    # @param name [Symbol] the scheme name
+    # @param scheme [Hash] the scheme data, constructed as described above
+    # @return [Hash] the frozen scheme data as it exists inside the module
     def add_brahmic_scheme(name, scheme)
       name = name.to_sym
       scheme = scheme.deep_dup
@@ -74,15 +78,12 @@ module Sanscript
       scheme
     end
 
-    #
     # Add a roman scheme to Sanscript.
     #
-    # See the comments on Sanscript.add_brahmic_scheme. The "vowel_marks" field
-    # can be omitted.
-    #
-    # @param name    the scheme name
-    # @param scheme  the scheme data itself
-    #
+    # @param name [Symbol] the scheme name
+    # @param scheme [Hash] the scheme data, constructed as in {add_brahmic_scheme}.
+    #                      The "vowel_marks" field can be omitted
+    # @return [Hash] the frozen scheme data as it exists inside the module
     def add_roman_scheme(name, scheme)
       name = name.to_sym
       scheme = scheme.deep_dup
@@ -93,13 +94,6 @@ module Sanscript
       scheme
     end
 
-    #
-    # Create a deep copy of an object, for certain kinds of objects.
-    #
-    # @param scheme  the scheme to copy
-    # @return        the copy
-    #
-
     # Set up various schemes
     begin
       # Re-add existing Brahmic schemes in order to add them to `scheme_names`
@@ -136,16 +130,15 @@ module Sanscript
       @all_alternates.each { |_, scheme| scheme.deep_freeze }
     end
 
-    # /**
     # Transliterate from one script to another.
-    #  *
-    # @param data     the string to transliterate
-    # @param from     the source script
-    # @param to       the destination script
-    # @param options  transliteration options
-    # @return         the finished string
     #
-    def transliterate(data, from, to, options = {})
+    # @param data [String] the String to transliterate
+    # @param from [Symbol] the source script
+    # @param to [Symbol] the destination script
+    # @option opts [Boolean] :skip_sgml (false) escape SGML-style tags in text string
+    # @option opts [Boolean] :syncope (false) activate Hindi-style schwa syncope
+    # @return [String] the transliterated string
+    def transliterate(data, from, to, **opts)
       from = from.to_sym
       to = to.to_sym
       return data if from == to
@@ -153,7 +146,7 @@ module Sanscript
       raise "Scheme not known ':#{to}'" unless @schemes.key?(to)
 
       data = data.to_str.dup
-      options = @defaults.merge(options)
+      options = @defaults.merge(opts)
       map = make_map(from, to)
 
       data.gsub!(/(<.*?>)/, "##\\1##") if options[:skip_sgml]
@@ -175,13 +168,12 @@ module Sanscript
     class << self
       private
 
-      #
       # Create a map from every character in `from` to its partner in `to`.
       # Also, store any "marks" that `from` might have.
       #
-      # @param from     input scheme
-      # @param to       output scheme
-      #
+      # @param from [Symbol] name of input scheme
+      # @param to [Symbol] name of output scheme
+      # @return [Hash] a mapping from one scheme to another
       def make_map(from, to)
         @cache[:"#{from}_#{to}"] ||= begin
           alternates = @all_alternates[from] || {}
@@ -229,16 +221,12 @@ module Sanscript
         end
       end
 
-      #
       # Transliterate from a romanized script.
       #
-      # @param data     the string to transliterate
-      # @param map      map data generated from makeMap()
-      # @param options  transliteration options
-      # @return         the finished string
-      #
+      # @param data [String] the string to transliterate
+      # @param map [Hash] map data generated from {#make_map}
+      # @return [String] the transliterated string
       def transliterate_roman(data, map, options = {})
-        options = @defaults.merge(options)
         data = data.to_str.dup
         buf = []
         token_buffer = String.new
@@ -308,13 +296,11 @@ module Sanscript
         buf.join("")
       end
 
-      #
       # Transliterate from a Brahmic script.
       #
-      # @param data     the string to transliterate
-      # @param map      map data generated from makeMap()
-      # @return         the finished string
-      #
+      # @param data [String] the string to transliterate
+      # @param map [Hash] map data generated from {#make_map}
+      # @return [String] the transliterated string
       def transliterate_brahmic(data, map)
         data = data.to_str.dup
         buf = []

data/lib/sanscript/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 module Sanscript
-  VERSION = "0.3.3"
+  # The version number
+  VERSION = "0.4.0"
 end

data/sanscript.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "codeclimate-test-reporter", "~> 0.6"
   spec.add_development_dependency "pry", "~> 0.10"
   spec.add_development_dependency "benchmark-ips", "~> 2.6"
+  spec.add_development_dependency "yard", "~> 0.9"
 
   spec.add_runtime_dependency "ice_nine", "~> 0.11"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sanscript
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Tim Bellefleur
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: ice_nine
   requirement: !ruby/object:Gem::Requirement
@@ -155,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.4
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby port and extension of Sanscript.js transliterator by learnsanskrit.org