knjrbfw 0.0.30 → 0.0.31

data/lib/knj/errors.rb

@@ -1,10 +1,21 @@
 #This module contains various extra errors used by the other Knj-code.
 module Knj::Errors
+  #An error that is used when the error is just a notice.
   class Notice < StandardError; end
+  
+  #Typically used when an object is not found by the given arguments.
   class NotFound < StandardError; end
+  
+  #If invalid data was supplied to a list-method or something like it.
   class InvalidData < StandardError; end
+  
+  #An error that specifies that the caller should retry the operation.
   class Retry < StandardError; end
+  
+  #The current env does not have access to calling the method.
   class NoAccess < StandardError; end
+  
+  #The thing you are trying to add already exists or have already been done.
   class Exists < StandardError; end
   
   #Returns a string describing the given error. Possible arguments can be given if you want the returned string formatted as HTML.

data/lib/knj/eruby.rb

@@ -1,6 +1,8 @@
+#Uses Rubinius, Knj::Compiler, RubyVM::InstructionSequence and eval to convert and execute .rhtml-files.
 class Knj::Eruby
   attr_reader :connects, :error, :headers, :cookies, :fcgi
   
+  #Sets various arguments and prepares for parsing.
   def initialize(args = {})
     @args = args
     
@@ -33,6 +35,9 @@ class Knj::Eruby
     self.reset_connects
   end
   
+  #Imports and evaluates a new .rhtml-file.
+  #===Examples
+  # erb.import("/path/to/some_file.rhtml")
   def import(filename)
     @error = false
     Dir.mkdir(@tmpdir) if !File.exists?(@tmpdir)
@@ -86,6 +91,7 @@ class Knj::Eruby
     end
   end
   
+  #Destroyes this object unsetting all variables and clearing all cache.
   def destroy
     @connects.clear if @connects.is_a?(Hash)
     @headers.clear if @headers.is_a?(Array)
@@ -100,6 +106,7 @@ class Knj::Eruby
     @cookies = nil
   end
   
+  #Returns various headers as one complete string ready to be used in a HTTP-request.
   def print_headers(args = {})
     header_str = ""
     
@@ -116,6 +123,7 @@ class Knj::Eruby
     return header_str
   end
   
+  #Returns true if containing a status-header.
   def has_status_header?
     @headers.each do |header|
       return true if header[0] == "Status"
@@ -124,23 +132,28 @@ class Knj::Eruby
     return false
   end
   
+  #Resets all connections.
   def reset_connects
     @connects = {}
   end
   
+  #Resets all headers.
   def reset_headers
     @headers = []
     @cookies = []
   end
   
+  #Adds a new header to the list.
   def header(key, value)
     @headers << [key, value]
   end
   
+  #Adds a new cookie to the list.
   def cookie(cookie_data)
     @cookies << cookie_data
   end
   
+  #Connects a block to a certain event.
   def connect(signal, &block)
     @connects[signal] = [] if !@connects.key?(signal)
     @connects[signal] << block
@@ -238,11 +251,14 @@ class Knj::Eruby
   end
 end
 
+#Erubis-handler used to print to $stdout.
 class Knj::Eruby::Handler < Erubis::Eruby
   include Erubis::StdoutEnhancer
 end
 
+#Default binding-object which makes sure the .rhtml-file is running on an empty object.
 class Knj::Eruby::Binding
+  #Returns the binding to the empty object.
   def get_binding
     return binding
   end

data/lib/knj/event_handler.rb

@@ -1,9 +1,22 @@
+#This class is used for event handeling.
+#===Examples
+# events = Knj::Event_handler.new
+# events.add_event(:name => :test_event)
+# events.connect(:test_event) do |*args|
+#   print "Test-event called!\n"
+# end
+# 
+# events.call(:test_event) #=> prints "Test-event called!\n"
 class Knj::Event_handler
+  #Sets various used variables.
   def initialize(args = {})
     @args = args
     @events = {}
   end
   
+  #Adds information about a new event.
+  #===Examples
+  # events.add_event(:name => :test_event)
   def add_event(event)
     raise "No name given." if !event[:name]
     
@@ -15,12 +28,18 @@ class Knj::Event_handler
     }
   end
   
+  #Adds multiple events.
+  #===Examples
+  # events.add_events(:test_event, :another_event, :a_third_event)
   def add_events(*events)
     events.each do |event|
       self.add_event(:name => event)
     end
   end
   
+  #Connects the given block to a given event.
+  #===Examples
+  # events.connect(:test_event){ |*args| print "Test event!\n"}
   def connect(name, &block)
     raise "No such event: '#{name}'." if !@events.key?(name)
     
@@ -40,11 +59,18 @@ class Knj::Event_handler
   end
   
   #Returns true if the given event is connected.
+  #===Examples
+  # print "Test-event is connected!" if events.connected?(:test_event)
   def connected?(name)
-    return true if @events.key?(name)
-    return false
+    raise "No such event." if !@events.key?(name)
+    return !@events[name][:callbacks].empty?
   end
   
+  #Disconnects an event.
+  #===Examples
+  # connection_id = events.connect(:test_event){print "test event!}
+  # events.disconnect(:test_event, connection_id)
+  # events.call(:test_event) #=> Doesnt print 'test event!'.
   def disconnect(name, callback_id)
     raise "No such event: '#{name}'." if !@events.key?(name)
     raise "No such connection: '#{name}' --> '#{callback_id}'" if !@events[name].key?(callback_id)
@@ -52,16 +78,17 @@ class Knj::Event_handler
     @events[name].delete(callback_id)
   end
   
+  #Returns how many blocks have been connected to an event.
+  #===Examples
+  # print "More than five connections to test-event!" if events.count_events(:test_event) > 5
   def count_connects(name)
     raise "No such event." if !@events.key?(name)
     return @events[name][:callbacks].length
   end
   
-  def connected?(name)
-    raise "No such event." if !@events.key?(name)
-    return !@events[name][:callbacks].empty?
-  end
-  
+  #Calls an added event.
+  #===Examples
+  # events.call(:test_event, {:data => 1})
   def call(name, *args)
     raise "No such event: '#{name}'." if !@events.key?(name)
     event = @events[name]

data/lib/knj/gettext_fallback.rb

@@ -1,16 +1,21 @@
+#A fallback GetText implementation that basically returns the given strings, but can be useful for using methods that uses GetText without using an actual GetText implementation.
 module GetText
+  #Returns the given string.
   def self._(string)
     return string
   end
   
+  #Returns the given string.
   def _(string)
     return string
   end
   
+  #Returns the given string.
   def gettext(string)
     return string
   end
   
+  #Doesnt do anything.
   def bindtextdomain(temp1 = nil, temp2 = nil, temp3 = nil)
     #nothing here.
   end

data/lib/knj/gettext_threadded.rb

@@ -1,6 +1,12 @@
+#This class reads .po-files generated by something like POEdit and can be used to run multi-language applications or websites.
 class Knj::Gettext_threadded
-  attr_reader :langs, :args
+  #Hash that contains all translations loaded.
+  attr_reader :langs
   
+  #Config-hash that contains encoding and more.
+  attr_reader :args
+  
+  #Initializes various data.
   def initialize(args = {})
     @args = {
       :encoding => "utf-8"
@@ -10,7 +16,9 @@ class Knj::Gettext_threadded
     load_dir(@args["dir"]) if @args["dir"]
   end
   
-  #Loads a 'locales'-directory with .mo- and .po-files.
+  #Loads a 'locales'-directory with .mo- and .po-files and fills the '@langs'-hash.
+  #===Examples
+  # gtext.load_dir("#{File.dirname(__FILE__)}/../locales")
   def load_dir(dir)
     @dirs << dir
     check_folders = ["LC_MESSAGES", "LC_ALL"]
@@ -44,6 +52,10 @@ class Knj::Gettext_threadded
     end
   end
   
+  #Translates a given string to a given locale from the read .po-files.
+  #===Examples
+  # str = "Hello" #=> "Hello"
+  # gtext.trans("da_DK", str) #=> "Hej"
   def trans(locale, str)
     locale = locale.to_s
     str = str.to_s

data/lib/knj/gtk2.rb

@@ -1,3 +1,4 @@
+#Contains various methods for doing stuff quick using the Gtk2-extension.
 module Knj::Gtk2
   #Autoloader.
   def self.const_missing(name)
@@ -5,10 +6,15 @@ module Knj::Gtk2
     return Knj::Gtk2.const_get(name)
   end
   
-  def msgbox(p1, p2 = "warning", p3 = "Warning")
-    return Knj::Gtk2.msgbox(p1, p2, p3)
+  #Alias for self.msgbox.
+  def msgbox(*args, &block)
+    return Knj::Gtk2.msgbox(*args, &block)
   end
   
+  #Shows a dialog on the screen based on various arguments.
+  #===Examples
+  # Knj::Gtk2.msgbox("Message", "Title", "info")
+  # Knj::Gtk2.msgbox("Question", "Title", "yesno") #=> "yes"|"no"|"cancel"|"close"
   def self.msgbox(paras, type = "warning", title = nil)
     if paras.is_a?(Array)
       msg = paras[0]
@@ -151,6 +157,9 @@ module Knj::Gtk2
     end
   end
   
+  #Takes a Gtk::Builder-object and runs labels and titles through GetText.gettext in order to translate them.
+  #===Examples
+  # Knj::Gtk2.translate(builder_obj)
   def self.translate(builderob)
     builderob.objects.each do |object|
       class_str = object.class.to_s
@@ -163,6 +172,9 @@ module Knj::Gtk2
     end
   end
   
+  #Makes a Gtk::Table based on the given arguments.
+  #===Examples
+  # Knj::Gtk2.form([{"type" => "text", "name" => "txtname", "title" => _("Name")}]) #=> {"table" => <Gtk::Table>, "objects" => <Array>}
   def self.form(paras)
     table = Gtk::Table.new(paras.length, 2)
     table.row_spacings = 4
@@ -239,11 +251,15 @@ module Knj::Gtk2
     }
   end
   
+  #Takes a given object and sets its value.
+  #===Examples
+  # Knj::Gtk2.form_setval(text_obj, "Hejsa")
+  # Knj::Gtk2.form_setval(checkbox_obj, 1)
   def self.form_setval(object, val)
     if object.is_a?(Gtk::Entry)
       object.text = val.to_s
     elsif object.is_a?(Gtk::CheckButton)
-      if (val.to_s == "1")
+      if val.to_s == "1"
         object.active = true
       else
         object.active = false
@@ -253,11 +269,15 @@ module Knj::Gtk2
     end
   end
   
+  #Returns the value of an object regardless of that type the object is.
+  #===Examples
+  # Knj::Gtk2.form_getval(text_obj) #=> "Hejsa"
+  # Knj::Gtk2.form_getval(checkbox_obj) #=> "1"
   def self.form_getval(object)
     if object.is_a?(Gtk::Entry)
       return object.text
     elsif object.is_a?(Gtk::CheckButton)
-      if (object.active?)
+      if object.active?
         return "1"
       else
         return "0"
@@ -271,7 +291,9 @@ module Knj::Gtk2
   end
 end
 
+#Defines a shortcut-method on Gtk::Builder
 class Gtk::Builder
+  #Proxies to Knj::Gtk2.translate
   def translate
     return Knj::Gtk2.translate(self)
   end

data/lib/knj/image.rb

@@ -1,5 +1,14 @@
+#This class holds methods to manipulate images.
 class Knj::Image
   #This function can make rounded transparent corners on an image with a given radius. Further more it can also draw borders around the entire image in a given color and take the border into account.
+  #===Examples
+  # img = Magick::Image.read(path_str)
+  # Knj::Image.rounded_corners(
+  #   :img => img,
+  #   :radius => 25,
+  #   :border => 1,
+  #   :border_color => "#000000"
+  # )
   def self.rounded_corners(args)
     raise "No or invalid ':img' given: '#{args}'." if !args[:img]
     raise "No or invalid ':radius' given: '#{args}'." if !args[:radius].respond_to?("to_i") or args[:radius].to_i <= 0
@@ -154,11 +163,15 @@ class Knj::Image
   end
   
   #Returns the width relative to the height.
+  #===Examples
+  # Knj::Image.width_for_height(640, 480, 400) #=> 533
   def self.width_for_height(orig_width, orig_height, new_height)
     return (orig_width.to_f / (orig_height.to_f / new_height.to_f)).to_i
   end
   
   #Returns the height relative to the width.
+  #===Examples
+  # Knj::Image.height_for_width(640, 480, 533) #=> 399
   def self.height_for_width(orig_width, orig_height, new_width)
     return (orig_height.to_f / (orig_width.to_f / new_width.to_f)).to_i
   end

data/lib/knj/knjdb/dbtime.rb

@@ -1,6 +1,9 @@
+#This class helps handeling time-columns in databases.
 class Knj::Db::Dbtime
+  #These variables return information about the object.
   attr_reader :hours, :mins, :secs, :total_secs
   
+  #Initializes the object from arguments useually given by Knj::Datarow.
   def initialize(args)
     args = {:time => args} if args.is_a?(String)
     
@@ -20,10 +23,12 @@ class Knj::Db::Dbtime
     @total_secs += @secs
   end
   
+  #Returns the total amount of hours.
   def hours_total
     return (@total_secs.to_f / 3600)
   end
   
+  #Return the total amount of minutes.
   def mins_total
     return (@total_secs.to_f / 60)
   end

data/lib/knj/knjdb/revision.rb

@@ -248,7 +248,7 @@ class Knj::Db::Revision
             table_data["on_create_after"].call("db" => db, "table_name" => table_name, "table_data" => table_data)
           end
           
-          self.rows_init("db" => db, "table" => table_obj, "rows" => table_data["rows"]) if table_data["rows"]
+          rows_init("db" => db, "table" => table_obj, "rows" => table_data["rows"]) if table_data["rows"]
         end
       rescue Knj::Errors::Retry
         retry

data/lib/knj/kvm.rb

@@ -1,4 +1,10 @@
+#This class and subclasses holds various functionality to view status for Kvm-instances.
 class Knj::Kvm
+  #Lists all running Kvm-instances on this machine.
+  #===Examples
+  # Knj::Kvm.list do |kvm|
+  #   print kvm.pid
+  # end
   def self.list
     list = []
     
@@ -35,24 +41,32 @@ class Knj::Kvm
   end
 end
 
+#Describes each Kvm-instance.
 class Knj::Kvm::Machine
+  #Sets the data called from Knj::Kvm.list.
   def initialize(args)
     @args = args
   end
   
+  #Returns the PID of the Kvm-instance.
   def pid
     return @args[:pid]
   end
   
+  #Returns the name from the Kvm-instance.
   def name
     return @args[:name]
   end
   
+  #Returns the MAC from a network interfaces on the Kvm-instance.
   def mac
     raise "No MAC-address has been registered for this machine." if !@args.key?(:mac)
     return @args[:mac]
   end
   
+  #Returns what virtual interface the Kvm is using.
+  #===Examples
+  # kvm.iface #=> "vnet12"
   def iface
     if !@iface
       res = Knj::Os.shellcmd("ifconfig | grep \"#{self.mac[3, self.mac.length]}\"")
@@ -67,6 +81,9 @@ class Knj::Kvm::Machine
     return @iface
   end
   
+  #Returns various data about the networking (how much have been sent and recieved).
+  #===Examples
+  # kvm.net_status #=> {:tx => 1024, :rx => 2048}
   def net_status
     res = Knj::Os.shellcmd("ifconfig \"#{self.iface}\"")
     
@@ -83,6 +100,9 @@ class Knj::Kvm::Machine
     return ret
   end
   
+  #Returns various data about how much disk IO the Kvm-instance have been using.
+  #===Examples
+  # kvm.io_status #=> {:read_bytes => 1024, :write_bytes => 2048}
   def io_status
     io_status = File.read("/proc/#{self.pid}/io")