knjrbfw 0.0.29 → 0.0.30

data/lib/knj/errors.rb

@@ -1,3 +1,4 @@
+#This module contains various extra errors used by the other Knj-code.
 module Knj::Errors
   class Notice < StandardError; end
   class NotFound < StandardError; end
@@ -6,6 +7,14 @@ module Knj::Errors
   class NoAccess < StandardError; end
   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.
+  #
+  #===Examples
+  # begin
+  #   raise 'test'
+  # rescue => e
+  #   print Knj::Errors.error_str(e, :html => true)
+  # end
   def self.error_str(err, args = {})
     if !err.is_a?(Exception) and err.class.message != "Java::JavaLang::LinkageError"
       raise "Invalid object of class '#{err.class.name}' given."

data/lib/knj/hash_methods.rb

@@ -1,24 +1,34 @@
+#A normal hash that uses 'method_missing' to be able to call keys by using methods. It is heavily used by Knj::Objects and have some pre-defined methods because of it to optimize performance.
+#===Examples
+# hm = Knj::Hash_methods(:test => "Test")
+# print hm.test
 class Knj::Hash_methods < Hash
+  #Spawns the object and takes a hash as argument.
   def initialize(hash = {})
     self.update(hash)
   end
   
+  #Returns the db-key.
   def db
     return self[:db]
   end
   
+  #Returns the ob-key.
   def ob
     return self[:ob]
   end
   
+  #Returns the args-key.
   def args
     return self[:args]
   end
   
+  #Returns the data-key.
   def data
     return self[:data]
   end
   
+  #Proxies methods into the hash as keys.
   def method_missing(method, *args)
     method = method.to_sym
     return self[method] if self.key?(method)

data/lib/knj/http2.rb

@@ -1,5 +1,16 @@
 require "#{$knjpath}web"
 
+#This class tries to emulate a browser in Ruby without any visual stuff. Remember cookies, keep sessions alive, reset connections according to keep-alive rules and more.
+#===Examples
+# Knj::Http2.new(:host => "www.somedomain.com", :port => 80, :ssl => false, :debug => false) do |http|
+#  res = http.get("index.rhtml?show=some_page")
+#  html = res.body
+#  print html
+#  
+#  res = res.post("index.rhtml?choice=login", {"username" => "John Doe", "password" => 123})
+#  print res.body
+#  print "#{res.headers}"
+# end
 class Knj::Http2
   attr_reader :cookies, :args
   
@@ -44,6 +55,9 @@ class Knj::Http2
     end
   end
   
+  #Returns boolean based on the if the object is connected and the socket is working.
+  #===Examples
+  # print "Socket is working." if http.socket_working?
   def socket_working?
     return false if !@sock or @sock.closed?
     
@@ -58,6 +72,9 @@ class Knj::Http2
     return true
   end
   
+  #Destroys the object unsetting all variables and closing all sockets.
+  #===Examples
+  # http.destroy
   def destroy
     @args = nil
     @cookies = nil
@@ -133,6 +150,10 @@ class Knj::Http2
     end
   end
   
+  #Returns a result-object based on the arguments.
+  #===Examples
+  # res = http.get("somepage.html")
+  # print res.body #=> <String>-object containing the HTML gotten.
   def get(addr, args = {})
     begin
       @mutex.synchronize do
@@ -174,6 +195,10 @@ class Knj::Http2
     @request_last = Time.now
   end
   
+  #Returns the default headers for a request.
+  #===Examples
+  # headers_hash = http.default_headers
+  # print "#{headers_hash}"
   def default_headers(args = {})
     return args[:default_headers] if args[:default_headers]
     
@@ -213,6 +238,9 @@ class Knj::Http2
     return praw
   end
   
+  #Posts to a certain page.
+  #===Examples
+  # res = http.post("login.php", {"username" => "John Doe", "password" => 123)
   def post(addr, pdata = {}, args = {})
     begin
       @mutex.synchronize do
@@ -231,6 +259,9 @@ class Knj::Http2
     end
   end
   
+  #Posts to a certain page using the multipart-method.
+  #===Examples
+  # res = http.post_multipart("upload.php", {"normal_value" => 123, "file" => Tempfile.new(?)})
   def post_multipart(addr, pdata, args = {})
     begin
       @mutex.synchronize do
@@ -274,6 +305,7 @@ class Knj::Http2
     end
   end
   
+  #Returns a header-string which normally would be used for a request in the given state.
   def header_str(headers_hash, args = {})
     if @cookies.length > 0 and (!args.key?(:cookies) or args[:cookies])
       cstr = ""
@@ -301,6 +333,9 @@ class Knj::Http2
     args[:on_content].call(line) if args.key?(:on_content)
   end
   
+  #Reads the response after posting headers and data.
+  #===Examples
+  # res = http.read_response
   def read_response(args = {})
     @mode = "headers"
     @resp = Knj::Http2::Response.new
@@ -386,7 +421,10 @@ class Knj::Http2
     end
   end
   
-  def parse_header(line, args)
+  #Parse a header-line and saves it on the object.
+  #===Examples
+  # http.parse_header("Content-Type: text/html\r\n")
+  def parse_header(line, args = {})
     if match = line.match(/^(.+?):\s*(.+)#{@nl}$/)
       key = match[1].to_s.downcase
       
@@ -436,6 +474,8 @@ class Knj::Http2
     end
   end
   
+  #Parses the body based on given headers and saves it to the result-object.
+  # http.parse_body(str)
   def parse_body(line, args)
     if @resp.args[:http_version] = "1.1"
       return "break" if @length == 0
@@ -480,37 +520,58 @@ class Knj::Http2::Response
     @args[:body] = "" if !@args.key?(:body)
   end
   
+  #Returns headers given from the host for the result.
+  #===Examples
+  # headers_hash = res.headers
   def headers
     return @args[:headers]
   end
   
+  #Returns a certain header by name or false if not found.
+  #===Examples
+  # val = res.header("content-type")
   def header(key)
     return false if !@args[:headers].key?(key)
     return @args[:headers][key].first.to_s
   end
   
   #Returns true if a header of the given string exists.
+  #===Examples
+  # print "No content-type was given." if !http.header?("content-type")
   def header?(key)
     return true if @args[:headers].key?(key) and @args[:headers][key].first.to_s.length > 0
     return false
   end
   
+  #Returns the code of the result (200, 404, 500 etc).
+  #===Examples
+  # print "An internal error occurred." if res.code.to_i == 500
   def code
     return @args[:code]
   end
   
+  #Returns the HTTP-version of the result.
+  #===Examples
+  # print "We are using HTTP 1.1 and should support keep-alive." if res.http_version.to_s == "1.1"
   def http_version
     return @args[:http_version]
   end
   
+  #Returns the complete body of the result as a string.
+  #===Examples
+  # print "Looks like we caught the end of it as well?" if res.body.to_s.downcase.index("</html>") != nil
   def body
     return @args[:body]
   end
   
+  #Returns the charset of the result.
   def charset
     return @args[:charset]
   end
   
+  #Returns the content-type of the result as a string.
+  #===Examples
+  # print "This body can be printed - its just plain text!" if http.contenttype == "text/plain"
   def contenttype
     return @args[:contenttype]
   end

data/lib/knj/knjdb/libknjdb.rb

@@ -1,3 +1,16 @@
+#A wrapper of several possible database-types.
+#
+#===Examples
+# db = Knj::Db.new(:type => "mysql", :subtype => "mysql2", :db => "mysql", :user => "user", :pass => "password")
+# mysql_table = db.tables['mysql']
+# name = mysql_table.name
+# cols = mysql_table.columns
+#
+# db = Knj::Db.new(:type => "sqlite3", :path => "some_db.sqlite3")
+#
+# db.q("SELECT * FROM users") do |data|
+#   print data[:name]
+# end
 class Knj::Db
   #Autoloader.
   def self.const_missing(name)
@@ -44,6 +57,7 @@ class Knj::Db
     self.connect
   end
   
+  #Actually connects to the database. This is useually done automatically.
   def connect
     if @opts[:threadsafe]
       @conns = Knj::Threadhandler.new
@@ -64,6 +78,9 @@ class Knj::Db
     end
   end
   
+  #Spawns a new driver (useally done automatically).
+  #===Examples
+  # driver_instance = db.spawn
   def spawn
     raise "No type given." if !@opts[:type]
     
@@ -83,6 +100,7 @@ class Knj::Db
     return Kernel.const_get("KnjDB_#{@opts[:type]}").new(self)
   end
   
+  #Registers a driver to the current thread.
   def get_and_register_thread
     raise "KnjDB-object is not in threadding mode." if !@conns
     
@@ -98,6 +116,7 @@ class Knj::Db
     thread_cur[:knjdb][tid] = @conns.get_and_lock if !thread_cur[:knjdb][tid]
   end
   
+  #Frees the current driver from the current thread.
   def free_thread
     thread_cur = Thread.current
     tid = self.__id__
@@ -120,6 +139,7 @@ class Knj::Db
     end
   end
   
+  #The all driver-database-connections.
   def close
     @conn.close if @conn
     @conns.destroy if @conns
@@ -128,10 +148,12 @@ class Knj::Db
     @conns = nil
   end
   
+  #Clones the current database-connection with possible extra arguments.
   def clone_conn(args = {})
     return Knj::Db.new(@opts.clone.merge(args))
   end
   
+  #Copies the content of the current database to another instance of Knj::Db.
   def copy_to(db, args = {})
     data["tables"].each do |table|
       table_args = nil
@@ -167,6 +189,10 @@ class Knj::Db
     end
   end
   
+  #Returns the data of this database in a hash.
+  #===Examples
+  # data = db.data
+  # tables_hash = data['tables']
   def data
     tables_ret = []
     tables.list.each do |name, table|
@@ -178,6 +204,11 @@ class Knj::Db
     }
   end
   
+  #Simply inserts data into a table.
+  #
+  #===Examples
+  # db.insert(:users, {:name => "John", :lastname => "Doe"})
+  # id = db.insert(:users, {:name => "John", :lastname => "Doe"}, :return_id => true)
   def insert(tablename, arr_insert, args = {})
     self.conn_exec do |driver|
       sql = "INSERT INTO #{driver.escape_table}#{tablename.to_s}#{driver.escape_table} ("
@@ -213,6 +244,13 @@ class Knj::Db
     end
   end
   
+  #Simply and optimal insert multiple rows into a table in a single query.
+  #
+  #===Examples
+  # db.insert_multi(:users, [
+  #   {:name => "John", :lastname => "Doe"},
+  #   {:name => "Kasper", :lastname => "Johansen"}
+  # ])
   def insert_multi(tablename, arr_hashes)
     self.conn_exec do |driver|
       if driver.respond_to?(:insert_multi)
@@ -226,6 +264,10 @@ class Knj::Db
     end
   end
   
+  #Simple updates rows.
+  #
+  #===Examples
+  # db.update(:users, {:name => "John"}, {:lastname => "Doe"})
   def update(tablename, arr_update, arr_terms = {})
     return false if arr_update.empty?
     
@@ -286,6 +328,10 @@ class Knj::Db
     return self.q(sql, &block)
   end
   
+  #Returns a single row from a database.
+  #
+  #===Examples
+  # row = db.single(:users, {:lastname => "Doe"})
   def single(tablename, arr_terms = nil, args = {})
     args["limit"] = 1
     
@@ -299,6 +345,10 @@ class Knj::Db
   
   alias :selectsingle :single
   
+  #Deletes rows from the database.
+  #
+  #===Examples
+  # db.delete(:users, {:lastname => "Doe"})
   def delete(tablename, arr_terms)
     self.conn_exec do |driver|
       sql = "DELETE FROM #{driver.escape_table}#{tablename}#{driver.escape_table}"
@@ -313,6 +363,10 @@ class Knj::Db
     return nil
   end
   
+  #Internally used to generate SQL.
+  #
+  #===Examples
+  # sql = db.makeWhere({:lastname => "Doe"}, driver_obj)
   def makeWhere(arr_terms, driver)
     sql = ""
     
@@ -337,6 +391,11 @@ class Knj::Db
   end
   
   #Returns a driver-object based on the current thread and free driver-objects.
+  #
+  #===Examples
+  # db.conn_exec do |driver|
+  #   str = driver.escape('something̈́')
+  # end
   def conn_exec
     if Thread.current[:knjdb]
       tid = self.__id__
@@ -376,6 +435,12 @@ class Knj::Db
   end
   
   #Executes a query and returns the result.
+  #
+  #===Examples
+  # res = db.query('SELECT * FROM users')
+  # while data = res.fetch
+  #   print data[:name]
+  # end
   def query(string)
     if @debug
       print "SQL: #{string}\n"
@@ -392,6 +457,11 @@ class Knj::Db
   end
   
   #Execute an ubuffered query and returns the result.
+  #
+  #===Examples
+  # db.query_ubuf('SELECT * FROM users') do |data|
+  #   print data[:name]
+  # end
   def query_ubuf(string, &block)
     ret = nil
     
@@ -407,7 +477,14 @@ class Knj::Db
     return ret
   end
   
-  #Clones the connection, executes a unbuffered query and closes the connection again.
+  #Clones the connection, executes the given block and closes the connection again.
+  #
+  #===Examples
+  # db.cloned_conn do |conn|
+  #   conn.q('SELCET * FROM users') do |data|
+  #     print data[:name]
+  #   end
+  # end
   def cloned_conn(args = nil, &block)
     clone_conn_args = {
       :threadsafe => false
@@ -424,6 +501,11 @@ class Knj::Db
   end
   
   #Executes a query and returns the result. If a block is given the result is iterated over that block instead and it returns nil.
+  #
+  #===Examples
+  # db.q('SELECT * FROM users') do |data|
+  #   print data[:name]
+  # end
   def q(str, args = nil, &block)
     #If the query should be executed in a new connection unbuffered.
     if args
@@ -452,6 +534,9 @@ class Knj::Db
   end
   
   #Returns the last inserted ID.
+  #
+  #===Examples
+  # id = db.last_id
   def lastID
     self.conn_exec do |driver|
       return driver.lastID
@@ -461,6 +546,9 @@ class Knj::Db
   alias :last_id :lastID
   
   #Escapes a string to be safe-to-use in a query-string.
+  #
+  #===Examples
+  # db.q("INSERT INTO users (name) VALUES ('#{db.esc('John')}')")
   def escape(string)
     self.conn_exec do |driver|
       return driver.escape(string)
@@ -547,6 +635,10 @@ class Knj::Db
     return @indexes
   end
   
+  #Proxies the method to the driver.
+  #
+  #===Examples
+  # db.method_on_driver
   def method_missing(method_name, *args)
     self.conn_exec do |driver|
       if driver.respond_to?(method_name.to_sym)
@@ -558,6 +650,12 @@ class Knj::Db
   end
   
   #Beings a transaction and commits when the block ends.
+  #
+  #===Examples
+  # db.transaction do |db|
+  #   db.insert(:users, {:name => "John"})
+  #   db.insert(:users, {:name => "Kasper"})
+  # end
   def transaction
     self.query("START TRANSACTION")