pad_utils 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0d994307acebee505edfb95deac3c785681b8595
-  data.tar.gz: 84663dbf244c403d7f20cb105b9756d7f2ccff44
+  metadata.gz: d62721ccb2c8956e21afbd46701f70c4ed8b16d0
+  data.tar.gz: 880ccaa96f429c75831085cfaa4c06993bb3beb0
 SHA512:
-  metadata.gz: 1e350721bb28b31c559e34ac7ee2e728af50337a5624c5757cb61bfac56a57a66c0f3c4b924d4b61cf17944311bdeaa94e170b3003a55021eca2fbd54c0d697e
-  data.tar.gz: c91c8147eda9bda2bcd6888375a382a78698f1d6dfaff5c1c62cbef94981b75704befe0ad38928e7a95888641069b22ed273075d2d84f6f6981cc029cc762113
+  metadata.gz: 58c650731599b21858389934b0223cfd59780eca5e0206a345b8cf4878ca21a67233e09034c8cb4dc46240d311838d2989ff481ec285231b5fa5eb36a51fb6c2
+  data.tar.gz: f82659ed6c0f39447f064d2e9916c7b7078c145bb7c4d152bd4155d19810c0a0d76d2f3d40430ffce85ce7e261c91ad6310c18a42872b51859d8f96309e61202

data/README.md

@@ -2,6 +2,7 @@
 
 PadUtils is a simple gem containing common utilities and shortcuts. It is used in the [Padstone](http://padstone.io) app builder but can be embedded in any other Ruby project.
 
+It provides methods to work with text, JSON, hashes, time, to build cli menus and more.
 
 ## Installation
 
@@ -10,285 +11,9 @@ It's a Ruby gem. Install it like any other gem!
 `gem install pad_utils`
 
 
-## Usage
+## Documentation
 
-Just `require 'pad_utils'` within your code to access the following methods.
-
-
-### Build CLI menus
-
-
-#### 1. Yes/No menu
-
-Prompt user with a cli yes/no menu. Returns `true` or `false`.
-
-* `question`: the question to ask
-* `default`: the default answer
-
-`PadUtils.yes_no_menu(question: "Question?", default: "y")`
-
-
-#### 2. Open question menu
-
-Prompt user with a cli open question menu. Returns a `string`.
-
-`PadUtils.question_menu(question)`
-
-
-#### 3. Multiple choice menu
-
-Prompt user with a multiple choice menu. Returns a `symbol`.
-
-* `question`: the question to ask
-* `choices`: hash of choices (e.g. `{b: "blue", r: "red"}`)
-* `default`: symbol representing the default value. If none provided, last value in choices hash will be used.
-
-`PadUtils.choice_menu(question: "Question?", choices: {}, default: nil)`
-
-
-### Work with text
-
-
-#### 1. Convert a string to a Rubified name
-
-Convert a string into a proper "rubified" name. For example, 'app_name' will be converted to 'AppName'. Returns a `string`.
-
-`PadUtils.convert_to_ruby_name(value)`
-
-
-#### 2. Convert CamelCase to camel_case (underscores)
-
-Convert a `CamelCase` word to an underscored one, e.g. `camel_case`. Taken from the Rails [Inflector](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore) class. Returns a `string`.
-
-`PadUtils.underscore(val)`
-
-
-#### 3. Sanitize a string
-
-Sanitize a string by replacing special characters (including spaces) with underscores. Returns a `string`.
-
-`PadUtils.sanitize(value)`
-
-
-#### 4. Replace a string in a file
-
-Replace text within a file. `old_text` can either be a `string` or a `regex`. Doesn't return anything, overwrites `file`.
-
-`PadUtils.replace_in_file(file, old_text, new_text)`
-
-
-#### 5. Insert text before first occurence
-
-Insert text in a string or a file before the first occurence of a string. Returns a `string`. If `is_file` is `true`, overwrites `original` file.
-
-* `original`: the original string or filename
-* `tag`: occurence of string to find
-* `text`: string to insert
-* `is_file`: `true` if `original` is a filename (default), `false` if it's a `string`
-
-`PadUtils.insert_before_first(original: nil, tag: nil, text: nil, is_file: true)`
-
-
-#### 6. Insert text before last occurence
-
-Insert text in a string or a file before the last occurence of a string. Returns a `string`. If `is_file` is `true`, overwrites `original` file.
-
-* `original`: the original string or filename
-* `tag`: occurence of string to find
-* `text`: string to insert
-* `is_file`: `true` if `original` is a filename (default), `false` if it's a `string`
-
-`PadUtils.insert_before_last(original: nil, tag: nil, text: nil, is_file: true)`
-
-
-#### 7. Insert text after first occurence
-
-Insert text in a string or a file after the first occurence of a string. Returns a `string`. If `is_file` is `true`, overwrites `original` file.
-
-* `original`: the original string or filename
-* `tag`: occurence of string to find
-* `text`: string to insert
-* `is_file`: `true` if `original` is a filename (default), `false` if it's a `string`
-
-`PadUtils.insert_after_first(original: nil, tag: nil, text: nil, is_file: true)`
-
-
-#### 8. Insert text after last occurence
-
-Insert text in a string or a file after the last occurence of a string. Returns a `string`. If `is_file` is `true`, overwrites `original` file.
-
-* `original`: the original string or filename
-* `tag`: occurence of string to find
-* `text`: string to insert
-* `is_file`: `true` if `original` is a filename (default), `false` if it's a `string`
-
-`PadUtils.insert_after_last(original: nil, tag: nil, text: nil, is_file: true)`
-
-
-### JSON and Hash
-
-Few methods to convert JSON to deep symbolized hash and back.
-
-
-#### 1. Symbolize all keys in a hash
-
-Convert all keys and sub-keys to symbols in a hash. Emulates the `deep_symbolize_keys` found in [Rails](http://apidock.com/rails/Hash/deep_symbolize_keys). Returns a `Hash`.
-
-`PadUtils.deep_symbolize_hash_keys(hash)`
-
-
-#### 2. Convert a JSON string to a symbolized hash
-
-Returns a `Hash`.
-
-`PadUtils.json_to_hash(json)`
-
-
-#### 3. Load a JSON file and convert it to a symbolized hash
-
-Returns a `Hash`.
-
-`PadUtils.json_file_to_hash(json_filename)`
-
-
-#### 4. Convert a hash to JSON
-
-*Alias method on `to_json` for consistency.*
-
-Returns a `string`.
-
-`PadUtils.hash_to_json(hash)`
-
-
-#### 5. Write a hash to a JSON file
-
-Returns the file content as a `string`.
-
-`PadUtils..hash_to_json_file(filename, hash)`
-
-
-### Work with files
-
-Mostly, these are convenience methods aliasing existing Ruby methods. Implemented for consistency.
-
-
-#### 1. Delete a file
-
-Delete a file. If not found, doesn't raise any error.
-
-`delete_file(file_path)`
-
-
-#### 2. Does a file exist?
-
-Returns `true` or `false`.
-
-`PadUtils.file_exist?(file_path)`
-
-
-#### 3. Copy a file
-
-**Will override file if it already exists!**
-
-`PadUtils.copy_file(file_path, dest_dir)`
-
-
-#### 4. Move a file
-
-**Will not throw an error if original file doesn't exist!**
-
-`PadUtils.move_file(file_path, dest_file)`
-
-
-#### 5. Copy multiple files
-
-`PadUtils.copy_files(files_array, dest_dir)`
-
-
-#### 6. Copy all files
-
-Copy all files from a directory to another. *Will create destination if it doesn't exist*.
-
-`PadUtils.copy_all_files(source_dir, dest_dir)`
-
-
-#### 7. Create a directory
-
-Create a directory and subdirectories. **Won't complain if it already exists. Won't override content**.
-
-`PadUtils.create_directory(dir_name)`
-
-
-#### 8. Delete a directory and its content
-
-`PadUtils.delete_directory(dir_name)`
-
-
-#### 9. Read content of a file
-
-Returns a `string`.
-
-`PadUtils.get_file_content(filepath)`
-
-
-#### 10. Write to a file
-
-Write content to a file. Create it if it doesn't exist. **Overwrites it if it already exists!**.
-
-`PadUtils.write_to_file(filepath, content)`
-
-
-#### 11. Append to a file
-
-Append content to the end of a file. Create it if it doesn't exist.
-
-**It will write a newline character first. If you don't want that,
-set the `new_line` option to `false`**.
-
-`PadUtils.append_to_file(filepath, content, new_line = true)`
-
-
-### Logging
-
-By default, logs will go to `~/pad_logs/logs.txt`.
-
-* Change default path: `PadUtils.log_path = "/new/path/to/logs"`
-* Change default file name: `PadUtils.log_file = "my_logs.txt"`
-
-To log a message, you call `log` and pass it a `message` string. Optionally, you can also pass an `Exception` object in the parameters:
-
-`PadUtils.log(message, e = nil)`
-
-
-### Some time methods
-
-
-#### 1. Time to string timestamp
-
-Returns a `string` timestamp with the format `YYYYMMDDHHmmss` from a `Time` object.
-
-`PadUtils.time_to_stamp(val)`
-
-
-#### 2. String to time
-
-Returns a `Time` object from a timestamp with the format `YYYYMMDDHHmmss`
-
-`PadUtils.stamp_to_time(val)`
-
-
-#### 3. Time to readable string
-
-Returns a `string` readable timestamp with format `YYYY-MM-DD HH:mm:ss` from a `Time` object.
-
-`PadUtils.time_to_readable_stamp(val)`
-
-
-#### 4. Readable timestamp to time
-
-Returns a `Time` object from a readable timestamp `string` with format `YYYY-MM-DD HH:mm:ss`
-
-`PadUtils.readable_stamp_to_time(val)`
+PadUtils is fully documented at [padutils.padstone.io](http://padutils.padstone.io/PadUtils.html) using [YARD](http://www.rubydoc.info/gems/yard/).
 
 
 ## Contribute

data/bin/padutils

@@ -2,4 +2,5 @@
 
 require_relative "../lib/pad_utils"
 
+# CLI entry point calling {PadUtils.main}
 PadUtils::main ARGV

data/lib/pad_utils/pad_files.rb

@@ -6,70 +6,144 @@ module PadUtils
   # Most are wrappers on FileUtils existing methods. Having them here,
   # a user of PadUtils doesn't have to remember names and parameters.
 
-  # Delete a file. If not found, doesn't raise any error.
+  # Deletes a file.
+  #
+  # @param file_path [String] the file path and name
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.delete("path/to/file.txt")
   def self.delete_file(file_path)
     FileUtils.rm(file_path, force: true)
   end
 
-  # Just a wrapper on File.exist? for consistency.
+  # Checks if a file exists.
+  #
+  # @param file_path [String] the file path and name
+  # @return [Boolean]
+  # @example
+  #   PadUtils.file_exist?("path/to/file.txt")
   def self.file_exist?(file_path)
     File.exist?(file_path)
   end
 
-  # Just a wrapper on FileUtils.cp for consistency.
-  # Will override file if it already exists!
+  # Copies a file.
+  #
+  # @param file_path [String] the source file name and path
+  # @param dest_dir [String] the destination directory
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.copy_file("test.txt", "path/to/destination/directory")
   def self.copy_file(file_path, dest_dir)
     FileUtils.cp(file_path, dest_dir)
   end
 
-  # Just a wrapper on FileUtils.mv for consistency.
-  # Will not throw an error if original file doesn't exist
+
+  # Moves a file.
+  #
+  # @param file_path [String] the source file path and name
+  # @param dest_file [String] the destination path and name
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.move_file("source.txt", "path/to/destination/renamed.txt")
   def self.move_file(file_path, dest_file)
     FileUtils.mv(file_path, dest_file, force: true)
   end
 
-  # Copy an array of files
+  # Copies an array of files.
+  #
+  # @param files [Array<String>] the array of files paths and names to copy
+  # @param dest_dir [String] the destination path
+  # @return [Void] nothing
+  # @example
+  #   files = ["file1.txt", "path/to/file2.txt", "path/to/files/file3.txt"]
+  #   PadUtils.copy_files(files, "path/to/destination")
   def self.copy_files(files, dest_dir)
     files.each do |f|
       copy_file(f, dest_dir)
     end
   end
 
-  # Copy all files from a directory to another.
-  # Will create destination if it doesn't exist
+  # Copies all files from a directory.
+  #
+  # @note Will create the destination if it doesn't exist.
+  #   Files existing on destination but not on source won't be overwritten.
+  #
+  # @param orig_dir [String] the path to source directory
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.copy_all_files("path/to/source", "path/to/destination")
   def self.copy_all_files(orig_dir, dest_dir)
     FileUtils.copy_entry(orig_dir, dest_dir)
   end
 
-  # Create a directory and subdirectories
-  # Won't complain if it already exists. Won't override content.
+  # Creates a directory.
+  #
+  # @note Won't override directory content if it already exists.
+  #
+  # @param dir_name [String] the directory path and name
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.create_directory("path/to/dir")
   def self.create_directory(dir_name)
     FileUtils.mkdir_p(dir_name)
   end
 
-  # Delete a directory and its content.
-  # Just a wrapper for consistency.
+  # Deletes a directory and its content
+  #
+  # @param dir_name [String] the directory path and name
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.delete_directory("path/to/dir")
   def self.delete_directory(dir_name)
     FileUtils.rm_r(dir_name)
   end
 
-  # Reads content of a file. Method created for consistency.
+  # Reads the whole content of a file into a string.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param filepath [String] the file path and name
+  # @return [String] the content of the file
+  # @example
+  #   PadUtils.get_file_content("path/to/file.txt")
   def self.get_file_content(filepath)
     File.read(filepath)
   rescue Exception => e
     PadUtils.log("Error in get_file_content", e)
   end
 
-  # Write content to a file. Create it if it doesn't exist.
+  # Writes content to a file.
+  #
+  # @note Will create destination file if it doesn't exist.
+  #   Will also overwrite the file if it already exists.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param  filepath [String] the file path and name
+  # @param  content [String] the content to be written
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.write_to_file("path/to/file", "Hello\nThis is a test")
   def self.write_to_file(filepath, content)
     File.open(filepath, 'w') { |f| f.write(content)}
   rescue Exception => e
     PadUtils.log("Error in write_to_file", e)
   end
 
-  # Append content to the end of a file. Create it if it doesn't exist.
-  # It will write a newline character first. If you don't want that,
-  # set the new_line option to false.
+
+  # Appends content to a file.
+  #
+  # @note Will create the destination file if it doesn't exist.
+  #   It also prepends a newline character. Set new_line to false to change this.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param filepath [String] the file path and name
+  # @param content [String] the content to append
+  # @param new_line [Boolean] prepends a newline character
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.append_to_file("path/to/file.txt", "Append this!", false)
   def self.append_to_file(filepath, content, new_line = true)
     content = "\n#{content}" if new_line
     File.open(filepath, 'a') { |f| f.write("#{content}")}

data/lib/pad_utils/pad_json.rb

@@ -2,43 +2,74 @@ require 'json'
 
 module PadUtils
 
-  # Convert all keys and sub-keys to symbols in a hash.
-  # Emulates the deep_symbolize_keys found in Rails.
-  # Returns a Hash.
+  # Converts keys and sub-keys to symbols in a hash.
+  #
+  # Emulates Rails {http://apidock.com/rails/Hash/deep_symbolize_keys deep_symbolize_keys} method.
+  #
+  # @param hash [Hash] the hash to symbolize
+  # @return [Hash] the symbolized hash
+  # @example
+  #   h = {"name": "Nico", "age": 37, "computers": [{"model": "Mac Pro"}, {"model": "MacBook"}]}
+  #   PadUtils.deep_symbolize_hash_keys(h)
+  #   # => {:name => "Nico", :age => 37, :computers => [{:model => "Mac Pro"}, {:model => "MacBook"}]}
   def self.deep_symbolize_hash_keys(hash)
     return hash.collect { |e| deep_symbolize_hash_keys(e) } if hash.is_a?(Array)
     return hash.inject({}) { |sh,(k,v)| sh[k.to_sym] = deep_symbolize_hash_keys(v); sh } if hash.is_a?(Hash)
     hash
   end
 
-  # Convert a JSON string to a symbolized hash.
-  # Returns a hash.
+  # Converts a JSON string to a symbolized hash.
+  #
+  # Calls {PadUtils.deep_symbolize_hash_keys} on a JSON formatted string.
+  #
+  # @param json [String] the JSON string to convert
+  # @return [Hash] the symbolized hash
+  # @example
+  #   PadUtils.json_to_hash(a_json_string)
   def self.json_to_hash(json)
     h = JSON.parse(json)
     self.deep_symbolize_hash_keys(h)
   end
 
-  # Load a JSON file and convert it to a symbolized hash.
-  # Returns a hash.
+  # Converts a JSON file to a symbolized hash.
+  #
+  # Reads a JSON file and calls {PadUtils.deep_symbolize_hash_keys} on its content.
+  #
+  # @param json_file [String] the json file path and name
+  # @return [Hash] the symbolized hash
+  # @example
+  #   PadUtils.json_file_to_hash("path/to/file")
   def self.json_file_to_hash(json_file)
     jfile = PadUtils.get_file_content(json_file)
     h = JSON.parse(jfile)
     self.deep_symbolize_hash_keys(h)
   end
 
-  # Convert a hash to JSON. Alias method for consistency.
-  # Returns a string
+  # Convert a hash to a JSON string.
+  #
+  # @param hash [Hash] the hash to convert
+  # @return [String] the JSON string
+  # @example
+  #   h = {name: "Nico", age: 37}
+  #   PadUtils.hash_to_json(h) # => '{"name": "Nico", "age": 37}'
   def self.hash_to_json(hash)
     hash.to_json
   end
 
-  # Write a hash to a json file.
-  # Returns the file content as a string.
+  # Writes a hash to a JSON file.
+  #
+  # @note Will overwrite the file if it already exists.
+  #
+  # @param filename [String] the file path and name to write to
+  # @param hash [Hash] the hash to convert to JSON and write
+  # @return [String] the JSON string
+  # @example
+  #   h = {name: "Nico", age: 37}
+  #   PadUtils.hash_to_json_file("path/to/json_file.txt", h) # => '{"name": "Nico", "age": 37}'
   def self.hash_to_json_file(filename, hash)
     json = hash.to_json
     PadUtils.write_to_file(filename, json)
     json
   end
 
-
 end

data/lib/pad_utils/pad_logger.rb

@@ -3,29 +3,54 @@ module PadUtils
   # Module variable holding the log path. By default,
   # logs will go in ~/pad_logs/
   @@log_path = "#{ENV["HOME"]}/pad_logs"
-  
+
   # Module variable holding the log file. By default,
   # logs will go in @@log_path/logs.txt
   @@log_file = "logs.txt"
-  
-  # Set another log path
+
+  # Sets a different log path.
+  #
+  # @param val [String] the path to the directory
+  # @return [String] the log directory path
+  # @example
+  #   PadUtils.set_log_path("path/directory") # => 'path/directory'
   def self.set_log_path(val)
     @@log_path = val
   end
-  
-  # Set another log file
+
+  # Sets a different log file.
+  #
+  # @param val [String] the log file name
+  # @return [String] the log file name
+  # @example
+  #   PadUtils.set_log_file("my_logs.txt") # => 'my_logs.txt'
   def self.set_log_file(val)
     @@log_file = val
   end
-  
-  # Log a message
+
+  # Logs a message.
+  #
+  # @note If using the method within a rescue block, pass the exception from
+  #   `rescue Exception => e`
+  #
+  # @param message [String] the message to log
+  # @param e [Exception] the raised exception
+  # @return [Void] nothing
+  # @example
+  #   def faulty_method
+  #     a = 0
+  #     b = 3
+  #     c = b / a
+  #   rescue Exception => e
+  #     PadUtils.log("Something bad happened!", e)
+  #   end
   def self.log(message, e = nil)
     # Create the log directory if it doesn't exist
     PadUtils.create_directory(@@log_path)
-    
+
     # Add a timestamp to the message
     message = "#{PadUtils.time_to_stamp(Time.now)}: #{message}"
-    
+
     # If an error is added, add its inner message to the message
     # as well as the whole stack
     if e != nil
@@ -36,9 +61,9 @@ module PadUtils
       end
       message = "#{message}\n"
     end
-    
+
     # Adds the message to the log file
-    PadUtils.append_to_file("#{@@log_path}/#{@@log_file}", message)    
+    PadUtils.append_to_file("#{@@log_path}/#{@@log_file}", message)
   end
-    
-end
+
+end

data/lib/pad_utils/pad_menu.rb

@@ -1,30 +1,48 @@
 module PadUtils
 
-  # Prompt user with a cli yes/no menu. Returns true or false.
-  # question: the question to ask
-  # default: the default answer
+  # Builds a `yes/no` cli menu.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param question [String] the question to ask
+  # @param default [String] the default answer as `"y"` or `"n"` - (*default: `"y"`*)
+  # @return [String] the answer as `"y"` or `"n"`
+  # @example
+  #   PadUtils.yes_no_menu("Is it cold outside?", default: "n")
   def self.yes_no_menu(question: "Question?", default: "y")
     default_answer = default == "y" ? "(Y/n)" : "(y/N)"
     STDOUT.print "#{question} #{default_answer}: "
     answer = STDIN.gets.chomp.strip.downcase
     answer = default if answer.length < 1
     answer == "y"
-    
   rescue Exception => e
     PadUtils.log("Error in yes/no menu", e)
   end
 
-  # Prompt user with a cli open question menu. Returns a string.
+  # Builds an open question menu.
+  #
+  # Will add `:` and a space after the question.
+  #
+  # @param question [String] the question to ask
+  # @return [String] the answer to the question
+  # @example
+  #   PadUtils.question_menu("How are you?") # => 'All good'
   def self.question_menu(question)
     STDOUT.print "#{question}: "
     STDIN.gets.chomp.strip
   end
 
-  # Prompt user with a multiple choice menu. Returns a symbol. Always!
-  # question: the question to ask
-  # choices: hash of choices (e.g. {b: "blue", r: "red"})
-  # default: symbol representing the default value. If none provided, last
-  #          value in choices hash will be used.
+  # Builds a multiple choice menu.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param question [String] the question to ask
+  # @param choices [Hash] the possible choices
+  # @param default [Symbol, nil] the default answer hash key. If nil, the last choice will be used.
+  # @return [Symbol] the chosen option
+  # @example
+  #   options = {r: "red", b: "blue", g: "green"}
+  #   PadUtils.choice_menu(question: "Which color?", choices: options, default: :b)
   def self.choice_menu(question: "Question?", choices: {}, default: nil)
     STDOUT.puts
     STDOUT.puts "- #{question}"
@@ -47,7 +65,6 @@ module PadUtils
     else
       return choices.keys[answer - 1].to_sym
     end
-
   rescue Exception => e
     PadUtils.log("Error in choice menu", e)
   end

data/lib/pad_utils/pad_text.rb

@@ -1,7 +1,15 @@
 module PadUtils
 
-  # Convert a string into a proper Ruby name.
-  # For example, 'app_name' will be converted to 'AppName'
+  # Converts a string to a Rubified name.
+  #
+  # @deprecated Use {PadUtils.camel_case PadUtils.camel_case} instead as it will
+  #   properly sanitize the string as well.
+  #
+  # @param value [String] the string to rubify
+  # @return [String] the rubified string
+  # @example
+  #   s = "hello_you"
+  #   PadUtils.convert_to_ruby_name(s) # => 'HelloYou'
   def self.convert_to_ruby_name(value)
     if value.scan(/\_|\-/).size > 0
       value.split(/\_|\-/).map(&:capitalize).join
@@ -10,8 +18,37 @@ module PadUtils
     end
   end
 
-  # Convert a CamelCase word to an underscored one, e.g. camel_case
-  # Taken from the Rails Inflector class.
+  # Converts a string to a CamelCase.
+  #
+  # @note The string will first be sanitized using {PadUtils.sanitize PadUtils.sanitize}.
+  #
+  # @param value [String] the string to CamelCase
+  # @return [String] the CamelCased string
+  # @example
+  #   s = "hello_you"
+  #   s2 = "hello you"
+  #   s3 = "hello   $you#"
+  #   PadUtils.convert_to_ruby_name(s) # => 'HelloYou'
+  #   PadUtils.convert_to_ruby_name(s2) # => 'HelloYou'
+  #   PadUtils.convert_to_ruby_name(s3) # => 'HelloYou'
+  def self.camel_case(value)
+    value = self.sanitize(value)
+    if value.scan(/\_|\-/).size > 0
+      value.split(/\_|\-/).map(&:capitalize).join
+    else
+      value.slice(0,1).capitalize + value.slice(1..-1)
+    end
+  end
+
+  # Converts a CamelCase string to an underscore string.
+  #
+  # Taken from the Rails {http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore Inflector}
+  # class.
+  #
+  # @param val [String] the CamelCase string to underscore
+  # @return [String] the under_score string
+  # @example
+  #   PadUtils.underscore("CamelCase") # => camel_case
   def self.underscore(val)
     word = val.dup
     word.gsub!(/::/, '/')
@@ -22,13 +59,28 @@ module PadUtils
     word
   end
 
-  # Convert a string to only alphanumeric and underscores
+  # Sanitizes a string.
+  #
+  # Will only allow alphanumeric characters and underscores.
+  #
+  # @param value [String] the string to sanitize
+  # @return [String] the sanitized string
+  # @example
+  #   PadUtils.sanitize("Abc Def *34*#yXz") # => 'Abc_Def__34__yXz'
   def self.sanitize(value)
     value.tr('^A-Za-z0-9', '_')
   end
 
-  # Replace text within a file.
-  # old_text can be a regex or a string
+  # Replaces text in a file.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param file [String] the file path and name
+  # @param old_text [String, Regexp] the text to find as a string or regex
+  # @param new_text [String] the new text
+  # @return [Void] nothing
+  # @example
+  #   PadUtils.replace_in_file("example.txt", /some_text/, "new text")
   def self.replace_in_file(file, old_text, new_text)
     text_update = PadUtils.get_file_content(file)
     text_update = text_update.gsub(old_text, new_text)
@@ -38,11 +90,19 @@ module PadUtils
     PadUtils.log("Error replacing #{old_text} in #{file} with #{new_text}", e)
   end
 
-  # Insert text in a string or a file before the first occurence of a string.
-  # original: the original string or filename
-  # tag: occurence of string to find
-  # text: string to insert
-  # is_file: say if original is a file (default: true) or a string
+  # Inserts text before the first occurence of a string.
+  #
+  # Can be used on a string or on a file.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param original [String] the original file path and name *or* the original string
+  # @param tag [String] the string to find
+  # @param text [String] the string to insert
+  # @param is_file [Boolean] `true` if `original` is a file, `false` if it is a string
+  # @return [String] the new content
+  # @example
+  #   PadUtils.insert_before_first(original: "file.txt", tag: "end", text: "# hello!")
   def self.insert_before_first(original: nil, tag: nil, text: nil, is_file: true)
     # The new text will be consolidated in content
     content = ""
@@ -81,11 +141,19 @@ module PadUtils
     PadUtils.log("Error in insert_before_first", e)
   end
 
-  # Insert text in a string or a file before the last occurence of a string.
-  # original: the original string or filename
-  # tag: occurence of string to find
-  # text: string to insert
-  # is_file: say if original is a file (default: true) or a string
+  # Inserts text before the last occurence of a string.
+  #
+  # Can be used on a string or on a file.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param original [String] the original file path and name *or* the original string
+  # @param tag [String] the string to find
+  # @param text [String] the string to insert
+  # @param is_file [Boolean] `true` if `original` is a file, `false` if it is a string
+  # @return [String] the new content
+  # @example
+  #   PadUtils.insert_before_last(original: "file.txt", tag: "end", text: "# hello!")
   def self.insert_before_last(original: nil, tag: nil, text: nil, is_file: true)
     # The new text will be consolidated in content
     content = ""
@@ -114,11 +182,19 @@ module PadUtils
     PadUtils.log("Error in insert_before_last", e)
   end
 
-  # Insert text in a string or a file after the first occurence of a string.
-  # original: the original string or filename
-  # tag: occurence of string to find
-  # text: string to insert
-  # is_file: say if original is a file (default: true) or a string
+  # Inserts text after the first occurence of a string.
+  #
+  # Can be used on a string or on a file.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param original [String] the original file path and name *or* the original string
+  # @param tag [String] the string to find
+  # @param text [String] the string to insert
+  # @param is_file [Boolean] `true` if `original` is a file, `false` if it is a string
+  # @return [String] the new content
+  # @example
+  #   PadUtils.insert_after_first(original: "file.txt", tag: "end", text: "# hello!")
   def self.insert_after_first(original: nil, tag: nil, text: nil, is_file: true)
     # The new text will be consolidated in content
     content = ""
@@ -157,11 +233,19 @@ module PadUtils
     PadUtils.log("Error in insert_after_first", e)
   end
 
-  # Insert text in a string or a file after the last occurence of a string.
-  # original: the original string or filename
-  # tag: occurence of string to find
-  # text: string to insert
-  # is_file: say if original is a file (default: true) or a string
+  # Inserts text after the last occurence of a string.
+  #
+  # Can be used on a string or on a file.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param original [String] the original file path and name *or* the original string
+  # @param tag [String] the string to find
+  # @param text [String] the string to insert
+  # @param is_file [Boolean] `true` if `original` is a file, `false` if it is a string
+  # @return [String] the new content
+  # @example
+  #   PadUtils.insert_after_last(original: "file.txt", tag: "end", text: "# hello!")
   def self.insert_after_last(original: nil, tag: nil, text: nil, is_file: true)
     # The new text will be consolidated in content
     content = ""

data/lib/pad_utils/pad_time.rb

@@ -2,25 +2,48 @@ require "time"
 
 module PadUtils
 
-  # Return a string timestamp with the format: YYYYMMDDHHmmss
+  # Returns a string timestamp.
+  #
+  # Format `YYYYMMDDHHmmss` will be used.
+  #
+  # @param val [Time] the Time object to convert
+  # @return [String] the timestamp
+  # @example
+  #   PadUtils.time_to_stamp(Time.now) # => 20160227160122
   def self.time_to_stamp(val)
     val.strftime("%Y%m%d%H%M%S")
   end
 
-  # Return a Time object from a timestamp with the format: YYYYMMDDHHmmss
+  # Returns a Time object from a string timestamp.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param val [String] a string formatted as `YYYYMMDDHHmmss`
+  # @return [Time] the Time object
+  # @example
+  #   PadUtils.stamp_to_time("20160227160122")
   def self.stamp_to_time(val)
     Time.parse "#{val[0..3]}-#{val[4..5]}-#{val[6..7]} #{val[8..9]}:#{val[10..11]}:#{val[12..13]}"
   rescue Exception => e
     PadUtils.log("Error in stamp_to_time", e)
   end
 
-  # Return a string readable timestamp with format: YYYY-MM-DD HH:mm:ss
+  # Returns a readable string timestamp.
+  #
+  # Format `YYYY-MM-DD HH:mm:ss` will be used.
+  #
+  # @param val [Time] the Time object to convert
+  # @return [String] the readable timestamp
   def self.time_to_readable_stamp(val)
     val.strftime("%Y-%m-%d %H:%M:%S")
   end
 
-  # Return a Time object from a PadUtils readable timestamp
-  # with format: YYYY-MM-DD HH:mm:ss
+  # Returns a Time object from a readable timestamp.
+  #
+  # Will log errors using {PadUtils.log PadUtils.log}.
+  #
+  # @param val [String] the readable timestamp formatted as `YYYY-MM-DD HH:mm:ss`
+  # @return [Time] the Time object
   def self.readable_stamp_to_time(val)
     Time.parse val
   rescue Exception => e

data/lib/pad_utils/version.rb

@@ -1,3 +1,4 @@
 module PadUtils
-  VERSION = "1.2.1"
+  # PadUtils version number
+  VERSION = "1.3.0"
 end

data/lib/pad_utils.rb

@@ -6,6 +6,11 @@ require_relative "pad_utils/pad_logger"
 require_relative "pad_utils/pad_menu"
 require_relative "pad_utils/pad_json"
 
+# Main namespace for PadUtils.
+#
+# Each method is implemented as a module method. Prefix them with PadUtils to call them.
+# @example
+#   PadUtils.some_method(param)
 module PadUtils
   # TODO: Add a cli coloring feature
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pad_utils
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Nico Schuele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-21 00:00:00.000000000 Z
+date: 2016-02-27 00:00:00.000000000 Z
 dependencies: []
 description: PadUtils is a simple gem containing common utilities and shortcuts. It
   is used in the [Padstone](http://padstone.io) app builder but can be embedded in
@@ -57,3 +57,4 @@ signing_key:
 specification_version: 4
 summary: PadUtils is a simple gem containing common utilities and shortcuts
 test_files: []
+has_rdoc: