rsl-stringex 0.9.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Lucky Sneaks
+
+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.rdoc

@@ -0,0 +1,74 @@
+= Stringex
+
+Some [hopefully] useful extensions to Ruby's String class. It is made up of three libraries: ActsAsUrl, Unidecoder, and StringExtensions.
+
+== ActsAsUrl
+
+This library is designed to create URI-friendly representations of an attribute, for use in generating urls from your attributes. Basic usage is just calling the method:
+
+  acts_as_url :title
+
+which will populate the <tt>url</tt> attribute on the object with the converted contents of the <tt>title</tt> attribute. This behavior can be customized by adding the following options to the arguments of the <tt>acts_as_url</tt> method:
+
+<tt>:url_attribute</tt>:: The name of the attribute to use for storing the generated url string.
+                          Default is <tt>:url</tt>
+<tt>:scope</tt>:: The name of model attribute to scope unique urls to. There is no default here.
+<tt>:sync_url</tt>:: If set to true, the url field will be updated when changes are made to the
+                     attribute it is based on. Default is false.
+                     
+In order to use the generated url attribute, you will probably want to override <tt>to_param</tt> like so, in your Model:
+
+  def to_param
+    url # or whatever you set :url_attribute to
+  end
+  
+Routing called via named routes like <tt>foo_path(@foo)</tt> will automatically use the url. In your controllers you will need to call <tt>Foo.find_by_url(params[:id])</tt> instead of the regular find. Don't look for <tt>params[:url]</tt> unless you set it explicitly in the routing, <tt>to_param</tt> will generate <tt>params[:id]</tt>.
+
+Unlike other permalink solutions, ActsAsUrl doesn't rely on Iconv (which is inconsistent across platforms and doesn't provide great transliteration as is) but instead uses a transliteration scheme (see the code for Unidecoder) which produces much better results for Unicode characters. It also mixes in some custom helpers to translate common characters into a more URI-friendly format rather than just dump them completely. Examples:
+
+   # A simple prelude
+   "simple English".to_url => "simple-english" 
+   "it's nothing at all".to_url => "its-nothing-at-all" 
+   "rock & roll".to_url => "rock-and-roll" 
+
+   # Let's show off
+   "$12 worth of Ruby power".to_url => "12-dollars-worth-of-ruby-power" 
+   "10% off if you act now".to_url => "10-percent-off-if-you-act-now" 
+
+   # You don't even wanna trust Iconv for this next part
+   "kick it en Français".to_url => "kick-it-en-francais" 
+   "rock it Español style".to_url => "rock-it-espanol-style" 
+   "tell your readers 你好".to_url => "tell-your-readers-ni-hao"
+   
+Compare those results with the ones produced on my Intel Mac by a leading permalink plugin:
+
+  "simple English" # => "simple-english" 
+  "it's nothing at all" # => "it-s-nothing-at-all"
+  "rock & roll" # => "rock-roll" 
+
+  "$12 worth of Ruby power" # => "12-worth-of-ruby-power" 
+  "10% off if you act now" # => "10-off-if-you-act-now" 
+
+  "kick it en Français" # => "kick-it-en-francais" 
+  "rock it Español style" # => "rock-it-espan-ol-style" 
+  "tell your readers 你好" # => "tell-your-readers"
+
+Not so great, actually.
+
+Note: No offense is intended to the author[s] of whatever plugins might produce such results. It's not your faults Iconv sucks.
+
+== Unidecoder
+
+This library converts Unicode [and accented Ascii] characters to their plain-text Ascii equivalents. This is a port of Perl's Unidecode and provides eminently superior and more reliable results than Iconv. (Seriously, Iconv... A plague on both your houses! [sic])
+
+You probably won't ever need to run Unidecoder by itself. StringExtensions adds String#to_ascii which wraps all of Unidecoder's functionality. For anyone interested, details of the implementation can be read about in the original implementation of Text::Unidecode[http://interglacial.com/~sburke/tpj/as_html/tpj22.html]. Extensive examples can be found in the tests. 
+
+== StringExtensions
+
+A collection of extensions on Ruby's String class. Please see the documentation for string_extensions module for more information. There's not much to explain about them really.
+
+== Thanks & Acknowledgements
+
+If it's not obvious, some of the code for ActsAsUrl is based on Rick Olsen's permalink_fu[http://svn.techno-weenie.net/projects/plugins/permalink_fu/] plugin. Unidecoder is a Ruby port of Sean Burke's Text::Unidecode[http://interglacial.com/~sburke/tpj/as_html/tpj22.html] module for Perl. And, finally, the bulk of strip_html_tags[link:classes/LuckySneaks/StringExtensions.html#M000005] in StringExtensions was stolen from Tobias Lütke's Regex in Typo[http://typosphere.org/].
+
+copyright (c) 2008 Lucky Sneaks, released under the MIT license

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => [:refresh_db, :test]
+
+desc 'Remove old sqlite file'
+task :refresh_db do
+  `rm -f #{File.dirname(__FILE__)}/test/acts_as_url.sqlite3`
+end
+
+desc 'Test the stringex plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the stringex plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'Stringex: A String Extension Pack'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,7 @@
+require 'lucky_sneaks/acts_as_url'
+require 'lucky_sneaks/string_extensions'
+require 'lucky_sneaks/unidecoder'
+
+String.send :include, LuckySneaks::StringExtensions
+
+ActiveRecord::Base.send :include, LuckySneaks::ActsAsUrl

data/lib/lucky_sneaks/acts_as_url.rb

@@ -0,0 +1,82 @@
+module LuckySneaks
+  module ActsAsUrl # :nodoc:
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods # :doc:
+      # Creates a callback to automatically create an url-friendly representation
+      # of the <tt>attribute</tt> argument. Example:
+      # 
+      #   act_as_url :title
+      # 
+      # will use the string contents of the <tt>title</tt> attribute
+      # to create the permalink. <strong>Note:</strong> you can also use a non-database-backed
+      # method to supply the string contents for the permalink. Just use that method's name
+      # as the argument as you would an attribute.
+      # 
+      # The default attribute <tt>acts_as_url</tt> uses to save the permalink is <tt>url</tt>
+      # but this can be changed in the options hash. Available options are:
+      # 
+      # <tt>:url_attribute</tt>:: The name of the attribute to use for storing the generated url string.
+      #                           Default is <tt>:url</tt>
+      # <tt>:scope</tt>:: The name of model attribute to scope unique urls to. There is no default here.
+      # <tt>:sync_url</tt>:: If set to true, the url field will be updated when changes are made to the
+      #                      attribute it is based on. Default is false.
+      def acts_as_url(attribute, options = {})
+        cattr_accessor :attribute_to_urlify
+        cattr_accessor :scope_for_url
+        cattr_accessor :url_attribute # The attribute on the DB
+        
+        if options[:sync_url]
+          before_validation :ensure_unique_url
+        else
+          before_validation_on_create :ensure_unique_url
+        end
+
+        self.attribute_to_urlify = attribute
+        self.scope_for_url = options[:scope]
+        self.url_attribute = options[:url_attribute] || "url"
+      end
+
+      # Initialize the url fields for the records that need it. Designed for people who add
+      # <tt>acts_as_url</tt> support once there's already development/production data they'd
+      # like to keep around.
+      # 
+      # Note: This method can get very expensive, very fast. If you're planning on using this
+      # on a large selection, you will get much better results writing your own version with
+      # using pagination.
+      def initialize_urls
+        find(:all, :conditions => {self.url_attribute => nil}).each do |instance|
+          instance.send :ensure_unique_url
+          instance.save
+        end
+      end
+    end
+      
+  private
+    def ensure_unique_url
+      url_attribute = self.class.url_attribute
+      base_url = self.send(self.class.attribute_to_urlify).to_s.to_url
+      conditions = ["#{url_attribute} LIKE ?", base_url+'%']
+      unless new_record?
+        conditions.first << " and id != ?"
+        conditions << id
+      end
+      if self.class.scope_for_url
+        conditions.first << " and #{self.class.scope_for_url} = ?"
+        conditions << send(self.class.scope_for_url)
+      end
+      url_owners = self.class.find(:all, :conditions => conditions)
+      if url_owners.size > 0
+        n = 1
+        while url_owners.detect{|u| u.send(url_attribute) == "#{base_url}-#{n}"}
+          n = n.succ
+        end
+        write_attribute url_attribute, "#{base_url}-#{n}"
+      else
+        write_attribute url_attribute, base_url
+      end
+    end
+  end
+end

data/lib/lucky_sneaks/string_extensions.rb

@@ -0,0 +1,165 @@
+module LuckySneaks
+  # These methods are all added on String class.
+  module StringExtensions
+    def self.included(base) # :nodoc:
+      base.extend(ClassMethods)
+    end
+    
+    # Returns the string converted (via Textile/RedCloth) to HTML format or
+    # self if Redcloth is not available.
+    # 
+    # Using <tt>:lite</tt> argument will cause RedCloth to not wrap the HTML in a container
+    # P element, which is useful behavior for generating header element text, etc.
+    # This is roughly equivalent to ActionView's <tt>textilize_without_paragraph</tt>
+    # except that it makes RedCloth do all the work instead of just gsubbing the return
+    # from RedCloth.
+    def to_html(lite_mode = false)
+      if defined?(RedCloth)
+        if lite_mode
+          RedCloth.new(self, [:lite_mode]).to_html
+        else
+          if self =~ /<pre>/
+            RedCloth.new(self).to_html.tr("\t", "")
+          else
+            RedCloth.new(self).to_html.tr("\t", "").gsub(/\n\n/, "")
+          end
+        end
+      else
+        self
+      end
+    end
+    
+    # Create a URI-friendly representation of the string. This is used internally by 
+    # acts_as_url[link:classes/LuckySneaks/ActsAsUrl/ClassMethods.html#M000012]
+    # but can be called manually in order to generate an URI-friendly version of any string.
+    def to_url
+      remove_formatting.downcase.replace_whitespace("-").collapse("-")
+    end
+    
+    # Performs multiple text manipulations. Essentially a shortcut for typing them all. View source
+    # below to see which methods are run.
+    def remove_formatting
+      to_ascii.strip_html_tags.convert_accented_entities.convert_misc_entities.convert_misc_characters.collapse
+    end
+
+    # Removes HTML tags from text. This code is simplified from Tobias Luettke's regular expression
+    # in Typo[http://typosphere.org].
+    def strip_html_tags(leave_whitespace = false)
+      name = /[\w:_-]+/
+      value = /([A-Za-z0-9]+|('[^']*?'|"[^"]*?"))/
+      attr = /(#{name}(\s*=\s*#{value})?)/
+      rx = /<[!\/?\[]?(#{name}|--)(\s+(#{attr}(\s+#{attr})*))?\s*([!\/?\]]+|--)?>/
+      (leave_whitespace) ?  gsub(rx, "").strip : gsub(rx, "").gsub(/\s+/, " ").strip
+    end
+
+    # Converts HTML entities into the respective non-accented letters. Examples:
+    # 
+    #   "&aacute;".convert_accented_entities # => "a"
+    #   "&ccedil;".convert_accented_entities # => "c"
+    #   "&egrave;".convert_accented_entities # => "e"
+    #   "&icirc;".convert_accented_entities # => "i"
+    #   "&oslash;".convert_accented_entities # => "o"
+    #   "&uuml;".convert_accented_entities # => "u"
+    # 
+    # Note: This does not do any conversion of Unicode/Ascii accented-characters. For that
+    # functionality please use <tt>to_ascii</tt>.
+    def convert_accented_entities
+      gsub(/&([A-Za-z])(grave|acute|circ|tilde|uml|ring|cedil|slash);/, '\1')
+    end
+
+    # Converts HTML entities (taken from common Textile/RedCloth formattings) into plain text formats.
+    # 
+    # Note: This isn't an attempt at complete conversion of HTML entities, just those most likely
+    # to be generated by Textile.
+    def convert_misc_entities
+      dummy = dup
+      {
+        "#822[01]" => "\"",
+        "#821[67]" => "'",
+        "#8230" => "...",
+        "#8211" => "-",
+        "#8212" => "--",
+        "#215" => "x",
+        "gt" => ">",
+        "lt" => "<",
+        "(#8482|trade)" => "(tm)",
+        "(#174|reg)" => "(r)",
+        "(#169|copy)" => "(c)",
+        "(#38|amp)" => "and",
+        "nbsp" => " ",
+        "(#162|cent)" => " cent",
+        "(#163|pound)" => " pound",
+        "(#188|frac14)" => "one fourth",
+        "(#189|frac12)" => "half",
+        "(#190|frac34)" => "three fourths",
+        "(#176|deg)" => " degrees"
+      }.each do |textiled, normal|
+        dummy.gsub!(/&#{textiled};/, normal)
+      end
+      dummy.gsub(/&[^;]+;/, "")
+    end
+
+    # Converts various common plaintext characters to a more URI-friendly representation.
+    # Examples:
+    #   
+    #   "foo & bar".convert_misc_characters # => "foo and bar"
+    #   "Chanel #9".convert_misc_characters # => "Chanel number nine"
+    #   "user@host".convert_misc_characters # => "user at host"
+    #   "google.com".convert_misc_characters # => "google dot com"
+    #   "$10".convert_misc_characters # => "10 dollars"
+    #   "*69".convert_misc_characters # => "star 69"
+    #   "100%".convert_misc_characters # => "100 percent"
+    #   "windows/mac/linux".convert_misc_characters # => "windows slash mac slash linux"
+    #   
+    # Note: Because this method will convert any & symbols to the string "and",
+    # you should run any methods which convert HTML entities (convert_html_entities and convert_misc_entities)
+    # before running this method.
+    def convert_misc_characters
+      dummy = dup.gsub(/\.{3,}/, " dot dot dot ") # Catch ellipses before single dot rule!
+      {
+        /\s*&\s*/ => "and",
+        /\s*#/ => "number",
+        /\s*@\s*/ => "at",
+        /(\S|^)\.(\S)/ => '\1 dot \2',
+        /(\s|^)\$(\d*)(\s|$)/ => '\2 dollars',
+        /\s*\*\s*/ => "star",
+        /\s*%\s*/ => "percent",
+        /\s*(\\|\/)\s*/ => "slash",
+      }.each do |found, replaced|
+        replaced = " #{replaced} " unless replaced =~ /\\1/
+        dummy.gsub!(found, replaced)
+      end
+      dummy = dummy.gsub(/(^|\w)'(\w|$)/, '\1\2').gsub(/[\.,:;()\[\]\/\?!\^'"_]/, " ")
+    end
+
+    # Replace runs of whitespace in string. Defaults to a single space but any replacement
+    # string may be specified as an argument. Examples:
+    # 
+    #   "Foo       bar".replace_whitespace # => "Foo bar"
+    #   "Foo       bar".replace_whitespace("-") # => "Foo-bar"
+    def replace_whitespace(replace = " ")
+      gsub(/\s+/, replace)
+    end
+
+    # Removes specified character from the beginning and/or end of the string and then performs
+    # <tt>String#squeeze(character)</tt>, condensing runs of the character within the string.
+    # 
+    # Note: This method has been superceded by ActiveSupport's squish method.
+    def collapse(character = " ")
+      sub(/^#{character}*/, "").sub(/#{character}*$/, "").squeeze(character)
+    end
+    
+    module ClassMethods
+      # Returns string of random characters with a length matching the specified limit. Excludes 0
+      # to avoid confusion between 0 and O.
+      def random(limit)
+        strong_alphanumerics = %w{
+          a b c d e f g h i j k l m n o p q r s t u v w x y z
+          A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
+          1 2 3 4 5 6 7 8 9
+        }
+        Array.new(limit, "").collect{strong_alphanumerics[rand(61)]}.join
+      end
+    end
+  end
+end

data/lib/lucky_sneaks/unidecoder.rb

@@ -0,0 +1,48 @@
+require "yaml"
+
+module LuckySneaks
+  module Unidecoder
+    # Contains Unicode codepoints, loading as needed from YAML files
+    CODEPOINTS = Hash.new { |h, k|
+      h[k] = YAML::load_file(File.join(File.dirname(__FILE__), "unidecoder_data", "#{k}.yml"))
+    } unless defined?(CODEPOINTS)
+  
+    class << self
+      # Returns string with its UTF-8 characters transliterated to ASCII ones
+      # 
+      # You're probably better off just using the added String#to_ascii
+      def decode(string)
+        string.gsub(/[^\x00-\x7f]/u) do |codepoint|
+          begin
+            CODEPOINTS[code_group(codepoint)][grouped_point(codepoint)]
+          rescue
+            # Hopefully this won't come up much
+            "?"
+          end
+        end
+      end
+    
+    private
+      # Returns the Unicode codepoint grouping for the given character
+      def code_group(character)
+        "x%02x" % (character.unpack("U")[0] >> 8)
+      end
+    
+      # Returns the index of the given character in the YAML file for its codepoint group
+      def grouped_point(character)
+        character.unpack("U")[0] & 255
+      end
+    end
+  end
+end
+
+module LuckySneaks
+  module StringExtensions
+    # Returns string with its UTF-8 characters transliterated to ASCII ones. Example: 
+    # 
+    #   "⠋⠗⠁⠝⠉⠑".to_ascii #=> "braille"
+    def to_ascii
+      LuckySneaks::Unidecoder::decode(self)
+    end
+  end
+end

data/lib/lucky_sneaks/unidecoder_data/x00.yml

@@ -0,0 +1,257 @@
+---
+- "\z"
+- "\x01"
+- "\x02"
+- "\x03"
+- "\x04"
+- "\x05"
+- "\x06"
+- "\a"
+- "\x08"
+- '	'
+- "\n"
+- "\v"
+- "\f"
+- "\r"
+- "\x0e"
+- "\x0f"
+- "\x10"
+- "\x11"
+- "\x12"
+- "\x13"
+- "\x14"
+- "\x15"
+- "\x16"
+- "\x17"
+- "\x18"
+- "\x19"
+- "\x1a"
+- "\e"
+- "\x1c"
+- "\x1d"
+- "\x1e"
+- "\x1f"
+- ' '
+- '!'
+- '"'
+- '#'
+- $
+- '%'
+- '&'
+- "'"
+- (
+- )
+- '*'
+- +
+- ','
+- -
+- .
+- /
+- 0
+- 1
+- 2
+- 3
+- 4
+- 5
+- 6
+- 7
+- 8
+- 9
+- ':'
+- ;
+- <
+- =
+- '>'
+- '?'
+- '@'
+- A
+- B
+- C
+- D
+- E
+- F
+- G
+- H
+- I
+- J
+- K
+- L
+- M
+- N
+- O
+- P
+- Q
+- R
+- S
+- T
+- U
+- V
+- W
+- X
+- Y
+- Z
+- ']'
+- \
+- ']'
+- '^'
+- _
+- '`'
+- a
+- b
+- c
+- d
+- e
+- f
+- g
+- h
+- i
+- j
+- k
+- l
+- m
+- n
+- o
+- p
+- q
+- r
+- s
+- t
+- u
+- v
+- w
+- x
+- y
+- z
+- '{'
+- '|'
+- '}'
+- '~'
+- 
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ''
+- ' '
+- '!'
+- C/
+- PS
+- $?
+- Y=
+- '|'
+- SS
+- '"'
+- (c)
+- a
+- <<
+- '!'
+- ''
+- (r)
+- -
+- deg
+- +-
+- 2
+- 3
+- "'"
+- u
+- P
+- '*'
+- ','
+- 1
+- o
+- '>>'
+- 1/4
+- 1/2
+- 3/4
+- '?'
+- A
+- A
+- A
+- A
+- A
+- A
+- AE
+- C
+- E
+- E
+- E
+- E
+- I
+- I
+- I
+- I
+- D
+- N
+- O
+- O
+- O
+- O
+- O
+- x
+- O
+- U
+- U
+- U
+- U
+- U
+- Th
+- ss
+- a
+- a
+- a
+- a
+- a
+- a
+- ae
+- c
+- e
+- e
+- e
+- e
+- i
+- i
+- i
+- i
+- d
+- n
+- o
+- o
+- o
+- o
+- o
+- /
+- o
+- u
+- u
+- u
+- u
+- y
+- th
+- y