sapis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31d4f98fb8910d18204ff9e5871480ac78185666f865e747ea86805024791530
+  data.tar.gz: cc9bc89dbb404f6014f6b0916d16e9c53d76eb8d67d741d31ff9d7bf43729732
+SHA512:
+  metadata.gz: 2dcf77bcecdcd1776e908cad92fb248256a0fe7359ffa8390818d456729f319d5ef2462f19ed77920944067440ebe6a19003ddf44aea808c044bf88d15b7292c
+  data.tar.gz: 438f3befe6b4fed326a2efc963282bccabc9646f9cc16589fe2da4989a5469a19970e8041f72c73ff75102cdcc0721ff34c82076842eee56b944b41882b73782

data/README.md

@@ -0,0 +1,179 @@
+# Sapis
+
+Sav's APIs - A collection of Ruby utility helpers for various tasks including graphing, configuration management, concurrency, system operations, multimedia handling, and more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sapis'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install sapis
+```
+
+## Usage
+
+Require the gem in your Ruby code:
+
+```ruby
+require 'sapis'
+```
+
+### Available Modules
+
+#### GraphingHelper
+
+Provides functionality for creating and formatting graphs using Gruff.
+
+```ruby
+# Transpose data and create line graphs
+data, days = GraphingHelper.transpose_data_top_headers( source_data )
+GraphingHelper.format_as_line_graph( data, days, out_file: 'graph.png' )
+
+# Format data as tables
+table = GraphingHelper.format_as_table( rows, separator: '|', align: { 'Header' => :left } )
+```
+
+#### ConfigurationHelper
+
+Load configuration from files with optional encryption support.
+
+```ruby
+config = ConfigurationHelper.load_configuration( group: 'myapp', sym_keys: true )
+value = config[ :some_key ]
+```
+
+#### ConcurrencyHelper
+
+Parallel processing with thread pooling.
+
+```ruby
+ConcurrencyHelper.with_parallel_queue( 4 ) do | queue, semaphore |
+  queue.push { task_1 }
+  queue.push { task_2 }
+end
+```
+
+#### GenericHelper
+
+General utility functions including date decoding and retry logic.
+
+```ruby
+date = GenericHelper.decode_date( 'today' )
+GenericHelper.do_retry( max_retries: 3, sleep: 1 ) { risky_operation }
+```
+
+#### BashHelper
+
+Safe execution of bash commands.
+
+```ruby
+result = BashHelper.safe_execute( 'ls -la' )
+BashHelper.simple_bash_execute( 'rm', file1, file2, file3 )
+```
+
+#### ComputationsHelper
+
+Data manipulation and smoothing functions.
+
+```ruby
+ComputationsHelper.convert_to_incremental_values!( values )
+ComputationsHelper.smooth_line!( values, 5 )
+```
+
+#### DesktopHelper
+
+Desktop integration utilities.
+
+```ruby
+DesktopHelper.set_clipboard_text( 'Hello, World!' )
+result = DesktopHelper.display_dialog( 'Are you sure?' )
+DesktopHelper.desktop_notification( 'Task completed' )
+```
+
+#### InteractionsHelper
+
+Command-line user interaction helpers.
+
+```ruby
+password = InteractionsHelper.secure_ask( 'Enter password: ' )
+answer = InteractionsHelper.ask_entry( 'Name', 'default_name' )
+choice = InteractionsHelper.ask_entries_with_points( 'Select option', options )
+```
+
+#### MultimediaHelper
+
+Audio and multimedia file operations.
+
+```ruby
+MultimediaHelper.play_audio_file( 'song.mp3' )
+MultimediaHelper.normalize_songs( file1, file2 )
+MultimediaHelper.create_m3u_playlist( files, basedir, 'playlist.m3u' )
+```
+
+#### GnomeHelper
+
+GNOME desktop environment helpers.
+
+```ruby
+GnomeHelper.set_gnome_background( '/path/to/image.jpg' )
+current = GnomeHelper.get_gnome_background_filename
+```
+
+#### SystemHelper
+
+System-level utilities.
+
+```ruby
+cores = SystemHelper.system_cores_number
+files = SystemHelper.find_files( '*.rb', [ '/path' ], file_type: SystemHelper::SEARCH_FILES )
+SystemHelper.open_file( 'document.pdf' )
+```
+
+#### SQLiteLayer
+
+Simplified SQLite database operations.
+
+```ruby
+db = SQLiteLayer.new( 'database.db' )
+id = db.insert_values( 'users', { name: 'John', email: 'john@example.com' } )
+results = db.select_all( 'SELECT * FROM users WHERE active = ?', true )
+db.transaction do
+  # database operations
+end
+db.close
+```
+
+## Dependencies
+
+- gruff (~> 0.7) - For graphing functionality
+- parseconfig (~> 1.0) - For configuration file parsing
+- highline (~> 2.0) - For secure command-line input
+- sqlite3 (~> 1.4) - For SQLite database operations
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0. See the source files for full license text.
+
+## Author
+
+Saverio Miroddi
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.

data/lib/sapis/bash_helper.rb

@@ -0,0 +1,80 @@
+=begin
+
+<bash_helper.rb> - Part of Sav's APIs.
+Copyright (C) 2011 Saverio Miroddi
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=end
+
+module BashHelper
+
+  require 'open3'
+  require 'shellwords'
+
+  # REFACTOR: default :out to STDOUT
+  #
+  def self.safe_execute( cmd, options={} )
+    out = options[ :out ]
+
+    Open3.popen3( cmd ) do | stdin, stdout, stderr, wait_thr |
+      exit_status = wait_thr.value.exitstatus
+
+      output = stdout.read
+
+      out << output if out
+
+      if exit_status == 0
+        output.chomp unless out
+      else
+        raise stderr.read.chomp
+      end
+    end
+  end
+
+  def safe_execute( cmd, options={} )
+    BashHelper.safe_execute( cmd, options )
+  end
+
+  # Encode as single-quoted, space-separated series of filenames.
+  # Encoding a slash apparently requires four slashes.
+  #
+
+  def simple_bash_execute( command, *files_and_options )
+    BashHelper.simple_bash_execute( command, *files_and_options )
+  end
+
+  def BashHelper.simple_bash_execute( command, *files_and_options )
+    options = files_and_options.last.is_a?( Hash ) ? files_and_options.pop : {}
+    files   = files_and_options
+
+    output = options.has_key?( :out ) ? options[ :out ] : STDOUT
+
+    files = files.flatten
+    command = "#{ command } #{ encode_bash_filenames( *files ) }"
+
+    safe_execute( command, out: output )
+  end
+
+  def encode_bash_filenames( *files )
+    BashHelper.encode_bash_filenames( *files )
+  end
+
+  def BashHelper.encode_bash_filenames( *files )
+    quoted_filenames = files.map { | file | file.shellescape }
+    quoted_filenames.join( ' ' )
+  end
+
+end
+

data/lib/sapis/computations_helper.rb

@@ -0,0 +1,95 @@
+=begin
+
+<computations_helper.rb> - Part of Sav's APIs.
+Copyright (C) 2011 Saverio Miroddi
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=end
+
+module ComputationsHelper
+
+  # Covnerts to incremental values.
+  #
+  # Modifies the original data.
+  #
+  # Example:
+  #   [ 1, 0, -1, 1 ]
+  # becomes:
+  #   [ 1, 1, 0,  1 ]
+  #
+  def self.convert_to_incremental_values!( source_values )
+    current_sum = 0
+
+    source_values.map! do | value |
+      if value
+        current_sum += value
+        current_sum
+      end
+    end
+  end
+
+  SMOOTHING_DATA = {
+    5 => [ 35.0,  [ -3, 12, 17, 12, -3 ] ],
+    7 => [ 21.0,  [ -2, 3, 6, 7, 6, 3, -2  ] ],
+    9 => [ 231.0, [ -21, 14, 39, 54, 59, 54, 39, 14, -21 ] ],
+  }
+
+  # Reference: http://stackoverflow.com/questions/4388911/how-can-i-draw-smoothed-rounded-curved-line-graphs-c
+  #
+  # Optimized for readability :-)
+  #
+  def self.smooth_line!( values, coefficients_number )
+    h, coefficients = SMOOTHING_DATA[ coefficients_number ] || raise( 'Wrong number of coefficients' )
+
+    raise "Smoothing needs at least #{ coefficients.size } values" if values.compact.size < coefficients.size
+
+    buffer_middle_position = ( coefficients.size + 1 ) / 2 - 1        # 0-based
+
+    non_empty_positions = []
+    original_values     = values.clone
+
+    # The complexity is caused by the presence of nil values.
+    # We cycle the array, and fill the buffer with the position of each non-null value encountered.
+    # When the buffer is ready, we compute the smoothed value and set it, and remove the first entry
+    # from the buffer.
+    #
+    values.each_with_index do | value, current_position |
+      non_empty_positions << current_position if value
+
+      next if non_empty_positions.size < coefficients.size
+
+      buffer             = non_empty_positions.map { | non_empty_position | original_values[ non_empty_position ] }
+      modifying_position = non_empty_positions[ buffer_middle_position ]
+
+      values[ modifying_position ] = compute_smoothed_point( buffer, coefficients, h )
+
+      non_empty_positions.shift
+    end
+
+    nil
+  end
+
+  private
+
+  def self.compute_smoothed_point( buffer, coefficients, h )
+    sum = buffer.zip( coefficients ).inject( 0 ) do | current_sum, ( value, coefficient ) |
+      current_sum + value * coefficient
+    end
+
+    sum / h
+  end
+
+end
+

data/lib/sapis/concurrency_helper.rb

@@ -0,0 +1,104 @@
+=begin
+
+<concurrency_helper.rb> - Part of Sav's APIs.
+Copyright (C) 2011 Saverio Miroddi
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=end
+
+module ConcurrencyHelper
+
+  require 'thread'
+
+  # Parallel working, constrained on the number of threads.
+  # Sets Thread.abort_on_exception to true as default.
+  #
+  # Usage:
+  #
+  #   ConcurrencyHelper.with_parallel_queue( <slots> ) do | queue, semaphore |
+  #     queue.push { <operation_1> }
+  #     queue.push { <operation_2> }
+  #   end
+  #
+  # or:
+  #
+  #   ConcurrencyHelper.with_parallel_queue( <slots>, :instances => <Enumerable> ) do | instance, semaphore |
+  #     -> { <operation>( <instance> ) }
+  #   end
+  #
+  # or:
+  #
+  #   queue = ParallelWorkersQueue.new( <threads> )
+  #   queue.push { <operation_1> }
+  #   queue.push { <operation_2> }
+  #   queue.join
+  #
+  # The semaphore is a generic semaphore; it can be used for example to lock when printing information to stdout.
+  #
+  class ParallelWorkersQueue
+
+    def initialize( slots, options={} )
+      abort_on_exception = ! options.has_key?( :abort_on_exception ) || options[ :abort_on_exception ]
+
+      @queue = SizedQueue.new( slots )
+
+      @threads = slots.times.map do
+        Thread.new do
+          while ( data = @queue.pop ) != :stop
+            data[]
+          end
+        end
+      end
+
+      Thread.abort_on_exception = abort_on_exception
+    end
+
+    def push( &task )
+      @queue.push( task )
+    end
+
+    def join
+      @threads.each do
+        @queue.push( :stop )
+      end
+
+      @threads.each( &:join )
+    end
+
+  end
+
+  def self.with_parallel_queue( slots, options={} )
+    instances          = options[ :instances          ]
+    abort_on_exception = options[ :abort_on_exception ]
+
+    queue     = ParallelWorkersQueue.new( slots, :abort_on_exception => abort_on_exception )
+    semaphore = Mutex.new
+
+    if instances
+      instances.each do | instance |
+        proc = yield( instance, semaphore )
+
+        raise "The value returned is not a Proc!" unless proc.is_a?( Proc )
+
+        queue.push( &proc )
+      end
+    else
+      yield( queue, semaphore )
+    end
+
+    queue.join
+  end
+
+end

data/lib/sapis/configuration_helper.rb

@@ -0,0 +1,128 @@
+=begin
+
+<configuration_helper.rb> - Part of Sav's APIs.
+Copyright (C) 2011 Saverio Miroddi
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=end
+
+module ConfigurationHelper
+
+  require 'rubygems'
+  require 'parseconfig'
+  require 'openssl'
+  require 'base64'
+
+  CONFIGURATION_FILE = File.expand_path( '.sav_scripts',     '~' )
+  PASSWORD_KEY_FILE  = File.expand_path( '.sav_scripts_key', '~' )
+
+  # The encryption is intentionally weak.
+  #
+  PASSWORD_CIPHER = 'des'
+  PASSWORD_KEY    = IO.read( PASSWORD_KEY_FILE ).chomp
+
+  # Loads the configuration from a file, for a given group.
+  #
+  # Returns a Hash with an extra method: :path(key), which interprets the value as an absolute path if it starts with
+  # a slash (/), and as a relative to home if it doesn't.
+  #
+  # options:
+  #   :group       manually specify the group; defaults to the calling script.
+  #   :sym_keys    keys as symbols
+  #   :file        configuration filename
+  #
+  def self.load_configuration( options={} )
+    $stderr.puts ">>> MIGRATE TO SIMPLE_SCRIPTING::CONFIG!"
+
+    raise "Change argument to :group if needed (when the filename is different from the group)" if options.is_a?( String )
+
+    group              = options[ :group    ] || File.basename( $0 ).chomp( '.rb' )
+    sym_keys           = options[ :sym_keys ]
+    configuration_file = options[ :file     ] || CONFIGURATION_FILE
+
+    configuration = ParseConfig.new( configuration_file )[ group ]
+
+    raise "Group not found in configuration: #{ group }" if configuration.nil?
+
+    if configuration[ 'password' ]
+      configuration[ 'password' ] = decrypt( configuration[ 'password' ], PASSWORD_KEY, PASSWORD_CIPHER, :base_64_decoding => true )
+    end
+
+
+    configuration = Hash[ configuration.map{ | key, value | [ key.to_sym, value ] } ] if sym_keys
+
+    def configuration.path( key )
+      raw_value = self[ key ]
+      raw_value.start_with?( '/' ) ? raw_value : File.expand_path( raw_value, '~' )
+    end
+
+    configuration
+  end
+
+  # Shortcut for the previous method.
+  #
+  # Returns a String when querying only one key, otherwise an Array.
+  #
+  def self.load_configuration_values( *keys )
+    configuration = load_configuration
+
+    values = keys.inject( [] ) do | current_values, key |
+      current_values << configuration[ key ]
+    end
+
+    if values.size == 1
+      values.first
+    else
+      values
+    end
+  end
+
+  def self.encrypt( plaintext, key, algo, options={} )
+    base_64_encoding = !! options[ :base_64_encoding ]
+
+    cipher = OpenSSL::Cipher::Cipher.new( algo )
+    cipher.encrypt
+
+    iv = cipher.random_iv
+
+    cipher.key = key
+    cipher.iv  = iv
+
+    ciphertext = iv + cipher.update( plaintext ) + cipher.final
+
+    ciphertext = Base64.encode64( ciphertext ) if base_64_encoding
+
+    ciphertext
+  end
+
+  def self.decrypt( ciphertext, key, algo, options={} )
+    puts ">>> ConfigurationHelper.decrypt should have key and algo as options"
+
+    base_64_decoding = !! options[ :base_64_decoding ]
+
+    ciphertext = Base64.decode64( ciphertext ) if base_64_decoding
+
+    cipher = OpenSSL::Cipher::Cipher.new( algo )
+    cipher.decrypt
+
+    cipher.key = key
+
+    cipher.iv = ciphertext.slice!( 0, cipher.iv_len )
+    plaintext = cipher.update( ciphertext ) + cipher.final
+
+    plaintext
+  end
+
+end

data/lib/sapis/desktop_helper.rb

@@ -0,0 +1,50 @@
+=begin
+
+<desktop_helper.rb> - Part of Sav's APIs.
+Copyright (C) 2011 Saverio Miroddi
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=end
+
+require_relative 'system_helper'
+require 'shellwords'
+
+module DesktopHelper
+  CLIPBOARD_COMMAND = "xi"
+
+  def set_clipboard_text( text )
+    IO.popen(CLIPBOARD_COMMAND, 'w' ) { | io | io << text }
+  end
+
+  # Displays an OK/Cancel dialog.
+  #
+  # Returns true for OK, false for Cancel/Esc.
+  #
+  def display_dialog( text )
+    quoted_text = '"' + text.gsub( '"', '\"' ).gsub( "'", "'\\\\''" ) + '"'
+
+    if SystemHelper.mac?
+      `osascript -e 'tell app "System Events" to display dialog #{ quoted_text }'`.strip == 'button returned:OK'
+    else
+      system( "zenity --question --text=#{ quoted_text }" )
+    end
+  end
+
+  def desktop_notification(text)
+    `notify-send #{text.shellescape}`
+  end
+
+end
+