smstools 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4180ff46eb40f9d709cf9895d1dc493aeec4203c
-  data.tar.gz: cba4fd705516f2418dfae93ce3732231e30faba5
+  metadata.gz: b0c466ba58b15a65599eb4abbaac0d22a6f82ac5
+  data.tar.gz: 416a9721a3ada4264dee86f28e1af344b24a8dbf
 SHA512:
-  metadata.gz: b3b26b73c00f2acbb9e107ecc24738b97a713a3579c685339226b9ba369c0d2080ff7b40357a472c0dc9ebe41bca0f8ed38e28cd132242ce7ed3e514a78d69c3
-  data.tar.gz: 9b7a0e6a64fdaec4f8f05130dc3b4ac735f2848fddfd1bbd8d274ec2b6e9781fcdb993ef121357e77f6b4c486508a067e6480516a72fd33d7c28007397f0fde5
+  metadata.gz: 1946b4d7493dfb0bd01d699f13ccd2ee7a2498daeb80b2f5070273031860e1189223837a785e8aca2c6e71bfcc63210dd7632bf8d105a80537b4264edf417df6
+  data.tar.gz: 2ca97dbb11cf51eb4493f152303dc5d81b6286ee83b4d7921fcaa01dcc195d0052d1d5dda7ae3b390637ce2d7285af23604c5f6822324b8a87a45e1316493b15

data/README.md

@@ -1,23 +1,70 @@
 # Sms Tools
 
-A small collection of useful Ruby and JavaScript classes implementing often
-needed functionality for dealing with SMS messages.
+A small collection of Ruby and JavaScript classes implementing often needed functionality for
+dealing with SMS messages.
 
-The gem is also a Rails engine and using it in your Rails app will allow you
-to also use the JavaScript classes via the asset pipeline.
+The gem can also be used in a Rails application as an engine. It integrates with the asset pipeline
+and gives you access to some clinet-side SMS manipulation functionality.
 
 ## Features
 
 The following features are available on both the server side and the client
 side:
 
-- Detection of the most optimal encoding for sending an SMS message (GSM 7-bit
-  or Unicode).
-- Correctly determining the message's length according to the most optimal
-  encoding.
+- Detection of the most optimal encoding for sending an SMS message (GSM 7-bit or Unicode).
+- Correctly determining a message's length in the most optimal encoding.
 - Concatenation detection and concatenated message parts counting.
 
-And more.
+The following can be accomplished only on the server with Ruby:
+
+- Converting a UTF-8 string to a GSM 7-bit encoding and vice versa.
+- Detecting if a UTF-8 string can be safely represented in a GSM 7-bit encoding.
+- Detection of double-byte chars in the GSM 7-bit encoding.
+
+And possibly more.
+
+### Note on the GSM encoding
+
+All references to the "GSM" encoding or the "GSM 7-bit alphabet" in this text actually refer to the
+[GSM 03.38 spec](http://en.wikipedia.org/wiki/GSM_03.38) and [its latest
+version](ftp://ftp.unicode.org/Public/MAPPINGS/ETSI/GSM0338.TXT), as defined by the Unicode
+consortium.
+
+This encoding is the most widely used one when sending SMS messages.
+
+### Note regarding non-ASCII symbols from the GSM encoding
+
+The GSM 03.38 encoding is used by default. This standard defines a set of
+symbols which can be encoded in 7-bits each, thus allowing up to 160 symbols
+per SMS message (each SMS message can contain up to 140 bytes of data).
+
+This standard covers most of the ASCII table, but also includes some non-ASCII
+symbols such as `æ`, `ø` and `å`. If you use these in your messages, you can
+still send them as GSM encoded, having a 160-symbol limit. This is technically
+correct.
+
+In reality, however, some SMS routes have problems delivering messages which
+contain such non-ASCII symbols in the GSM encoding. The special symbols might
+be omitted, or the message might not arrive at all.
+
+Thus, it might be safer to just send messages in Unicode if the message's text
+contains any non-ASCII symbols. This is not the default as it reduces the max
+symbols count to 70 per message, instead of 160, and you might not have any
+issues with GSM-encoded messages. In case you do, however, you can turn off
+support for the GSM encoding and just treat messages as Unicode if they contain
+non-ASCII symbols.
+
+In case you decide to do so, you have to specify it in both the Ruby and the
+JavaScript part of the library, like so:
+
+#### In Ruby
+
+    SmsTools.use_gsm_encoding = false
+
+#### In Javascript
+
+    //= require sms_tools
+    SmsTools.use_gsm_encoding = false;
 
 ## Installation
 
@@ -33,32 +80,99 @@ Or install it yourself as:
 
     $ gem install smstools
 
+If you're using the gem in Rails, you may also want to add the following to your `application.js`
+manifest file to gain access to the client-side features:
+
+    //= require sms_tools
+
 ## Usage
 
 The gem consists of both server-side (Ruby) and client-side classes. You can
-use either one.
+use either.
 
 ### Server-side code
 
-If you use the gem in Rails or via Bundler, just use the appropriate class,
-such as `SmsTools::EncodingDetection` or `SmsTools::GsmEncoding`.
+First make sure you have installed the gem and have required the appropriate files.
 
-#### `EncodingDetection`
-#### `GsmEncoding`
+#### Encoding detection
+
+The `SmsTools::EncodingDetection` class provides you with a few simple methods to detect the most
+optimal encoding for sending an SMS message, to correctly caclulate its length in that encoding and
+to see if the text would need to be concatenated or will fit in a single message.
+
+Here is an example with a non-concatenated message which is best encoded in the GSM 7-bit alphabet:
+
+```ruby
+sms_text     = 'Text in GSM 03.38: ÄäøÆ with a double-byte char: ~ '
+sms_encoding = SmsTools::EncodingDetection.new sms_text
+
+sms_encoding.gsm?               # => true
+sms_encoding.unicode?           # => false
+sms_encoding.length             # => 52 (because of the double-byte char)
+sms_encoding.concatenated?      # => false
+sms_encoding.concatenated_parts # => 1
+sms_encoding.encoding           # => :gsm
+```
+
+Here's another example with a concatenated Unicode message:
+
+```ruby
+sms_text     = 'Я' * 90
+sms_encoding = SmsTools::EncodingDetection.new sms_text
+
+sms_encoding.gsm?               # => false
+sms_encoding.unicode?           # => true
+sms_encoding.length             # => 90
+sms_encoding.concatenated?      # => true
+sms_encoding.concatenated_parts # => 2
+sms_encoding.encoding           # => :unicode
+```
+
+You can check the specs for this class for more examples.
+
+#### GSM 03.38 encoding conversion
+
+The `SmsTools::GsmEncoding` class can be used to check if a given UTF-8 string can be fully
+represented in the GSM 03.38 encoding as well as to convert from UTF-8 to GSM 03.38 and vice-versa.
+
+The main API this class provides is the following:
+
+```ruby
+SmsTools::GsmEncoding.valid? message_text_in_utf8   # => true or false
+
+SmsTools::GsmEncoding.from_utf8 utf8_encoded_string # => a GSM 03.38 encoded string
+SmsTools::GsmEncoding.to_utf8 gsm_encoded_string    # => an UTF-8 encoded string
+```
+
+Check out the source code of the class to find out more.
 
 ### Client-side code
 
-If you're using the gem in Rails 3.x or newer, you can just add the following
-to your `application.js` file to gain access to the JavaScript classes:
+If you're using the gem in Rails 3.1 or newer, you can gain access to the `SmsTools.Message` class.
+It's interface is similar to the one of `SmsTools::EncodingDetection`. Here is an example in
+CoffeeScript:
+
+```coffeescript
+message = new SmsTools.Message 'The text of the message: ~'
+
+message.encoding               # => 'gsm'
+message.length                 # => 27
+message.concatenatedPartsCount # => 1
+```
 
-    #= require 'sms_tools/all'
+You can also check how long can this message be in the current most optimal encoding, if we want to
+limit the number of concatenated messages we will allow to be sent:
 
-Or require only the files you need:
+```coffeescript
+maxConcatenatedPartsCount = 2
+message.maxLengthFor(maxConcatenatedPartsCount) # => 306
+```
 
-    #= require 'sms_tools/message'
+This allows you to have a dynamic instead of a fixed length limit, for when you use a non-GSM 03.38
+symbol in your text, your message length limit decreases significantly.
 
-Note that this assumes you're using the asset pipeline. You need to have a
-CoffeeScript preprocessor set up.
+Note that to use this client-side code, a Rails application with an active asset pipeline is
+assumed. It might be possible to use it in other setups as well, but you're on your own there.
 
 ## Contributing
 

data/lib/assets/javascripts/sms_tools/message.js.coffee

@@ -2,6 +2,9 @@ window.SmsTools ?= {}
 
 class SmsTools.Message
   maxLengthForEncoding:
+    ascii:
+      normal: 160
+      concatenated: 153
     gsm:
       normal: 160
       concatenated: 153
@@ -20,6 +23,7 @@ class SmsTools.Message
     '€':  true
     '\\': true
 
+  asciiPattern: /^[\x00-\x7F]*$/
   gsmEncodingPattern: /^[0-9a-zA-Z@Δ¡¿£_!Φ"¥Γ#èΛ¤éΩ%ùΠ&ìΨòΣçΘΞ:Ø;ÄäøÆ,<Ööæ=ÑñÅß>Üüåɧà€~ \$\.\-\+\(\)\*\\\/\?\|\^\}\{\[\]\'\r\n]*$/
 
   constructor: (@text) ->
@@ -33,8 +37,19 @@ class SmsTools.Message
 
     concatenatedPartsCount * @maxLengthForEncoding[@encoding][messageType]
 
+  use_gsm_encoding: ->
+    if SmsTools['use_gsm_encoding'] == undefined
+      true
+    else
+      SmsTools['use_gsm_encoding']
+
   _encoding: ->
-    if @gsmEncodingPattern.test(@text) then 'gsm' else 'unicode'
+    if @asciiPattern.test(@text)
+      'ascii'
+    else if @use_gsm_encoding() and @gsmEncodingPattern.test(@text)
+      'gsm'
+    else
+      'unicode'
 
   _concatenatedPartsCount: ->
     encoding = @encoding
@@ -45,9 +60,9 @@ class SmsTools.Message
     else
       parseInt Math.ceil(length / @maxLengthForEncoding[encoding].concatenated), 10
 
-   # Returns the number of symbols, which the given text will take up in an SMS
-   # message, taking into account any double-space symbols in the GSM 03.38
-   # encoding.
+  # Returns the number of symbols which the given text will eat up in an SMS
+  # message, taking into account any double-space symbols in the GSM 03.38
+  # encoding.
   _length: ->
     length = @text.length
 

data/lib/sms_tools.rb

@@ -5,3 +5,15 @@ require 'sms_tools/gsm_encoding'
 if defined?(::Rails) and ::Rails.version >= '3.1'
   require 'sms_tools/rails/engine'
 end
+
+module SmsTools
+  class << self
+    def use_gsm_encoding?
+      @use_gsm_encoding.nil? ? true : @use_gsm_encoding
+    end
+
+    def use_gsm_encoding=(value)
+      @use_gsm_encoding = value
+    end
+  end
+end

data/lib/sms_tools/encoding_detection.rb

@@ -3,6 +3,10 @@ require 'sms_tools/gsm_encoding'
 module SmsTools
   class EncodingDetection
     MAX_LENGTH_FOR_ENCODING = {
+      ascii: {
+        normal:       160,
+        concatenated: 153,
+      },
       gsm: {
         normal:       160,
         concatenated: 153,
@@ -20,7 +24,18 @@ module SmsTools
     end
 
     def encoding
-      @encoding ||= GsmEncoding.valid?(text) ? :gsm : :unicode
+      @encoding ||=
+        if text.ascii_only?
+          :ascii
+        elsif SmsTools.use_gsm_encoding? and GsmEncoding.valid?(text)
+          :gsm
+        else
+          :unicode
+        end
+    end
+
+    def ascii?
+      encoding == :ascii
     end
 
     def gsm?
@@ -49,9 +64,9 @@ module SmsTools
       concatenated_parts * MAX_LENGTH_FOR_ENCODING[encoding][message_type]
     end
 
-     # Returns the number of symbols, which the given text will take up in an SMS
-     # message, taking into account any double-space symbols in the GSM 03.38
-     # encoding.
+    # Returns the number of symbols which the given text will eat up in an SMS
+    # message, taking into account any double-space symbols in the GSM 03.38
+    # encoding.
     def length
       length = text.length
       length += text.chars.count { |char| GsmEncoding.double_byte?(char) } if gsm?

data/lib/sms_tools/version.rb

@@ -1,3 +1,3 @@
 module SmsTools
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/spec/sms_tools/encoding_detection_spec.rb

@@ -1,5 +1,5 @@
 require 'spec_helper'
-require 'sms_tools/encoding_detection'
+require 'sms_tools'
 
 describe SmsTools::EncodingDetection do
   it "exposes the original text as a method" do
@@ -7,27 +7,49 @@ describe SmsTools::EncodingDetection do
   end
 
   describe "encoding" do
-    it "defaults to GSM encoding for empty messages" do
-      detection_for('').encoding.must_equal :gsm
+    it "defaults to ASCII encoding for empty messages" do
+      detection_for('').encoding.must_equal :ascii
     end
 
-    it "returns GSM as encoding for simple ASCII text" do
-      detection_for('foo bar baz').encoding.must_equal :gsm
+    it "returns ASCII as encoding for simple ASCII text" do
+      detection_for('foo bar baz').encoding.must_equal :ascii
     end
 
     it "returns GSM as encoding for special symbols defined in GSM 03.38" do
       detection_for('09azAZ@Δ¡¿£_!Φ"¥Γ#èΛ¤éΩ%ùΠ&ìΨòΣçΘΞ:Ø;ÄäøÆ,<Ööæ=ÑñÅß>Üüåɧà€~').encoding.must_equal :gsm
     end
 
-    it "returns GSM as encoding for puntucation and newline symbols" do
-      detection_for('Foo bar {} [baz]! Larodi $5. What else?').encoding.must_equal :gsm
-      detection_for("Spaces and newlines are GSM 03.38, too: \r\n").encoding.must_equal :gsm
+    it "returns ASCII as encoding for puntucation and newline symbols" do
+      detection_for('Foo bar {} [baz]! Larodi $5. What else?').encoding.must_equal :ascii
+      detection_for("Spaces and newlines are GSM 03.38, too: \r\n").encoding.must_equal :ascii
     end
 
     it "returns Unicode when non-GSM Unicode symbols are used" do
       detection_for('Foo bar лароди').encoding.must_equal :unicode
       detection_for('∞').encoding.must_equal :unicode
     end
+
+    describe 'with SmsTools.use_gsm_encoding = false' do
+      before do
+        SmsTools.use_gsm_encoding = false
+      end
+
+      after do
+        SmsTools.use_gsm_encoding = true
+      end
+
+      it "returns Unicode as encoding for special symbols defined in GSM 03.38" do
+        detection_for('09azAZ@Δ¡¿£_!Φ"¥Γ#èΛ¤éΩ%ùΠ&ìΨòΣçΘΞ:Ø;ÄäøÆ,<Ööæ=ÑñÅß>Üüåɧà€~').encoding.must_equal :unicode
+      end
+
+      it 'returns ASCII for simple ASCII text' do
+        detection_for('Hello world.').encoding.must_equal :ascii
+      end
+
+      it "defaults to ASCII encoding for empty messages" do
+        detection_for('').encoding.must_equal :ascii
+      end
+    end
   end
 
   describe "message length" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smstools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Dimitar Dimitrov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-17 00:00:00.000000000 Z
+date: 2015-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -111,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Small library of classes for common SMS-related functionality.