cyberweb 0.4.174

data/lib/cyberweb/cgi/cgi.rb

@@ -0,0 +1,340 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file can be found at:
+#
+#   require 'cyberweb/cgi/cgi.rb'
+#
+# =========================================================================== #
+
+# =========================================================================== #
+# == Overview
+#
+# The "Common Gateway Interface" (CGI) is a simple protocol for passing an
+# HTTP request from a web server to a standalone program, and returning the
+# output to the web browser.
+#
+# Basically, a CGI program is called with the parameters of the request
+# passed in either in the environment (GET) or via $stdin (POST), and
+# everything it prints to $stdout is returned to the client.
+#
+# This file holds the CGI class.  This class provides functionality for
+# retrieving HTTP request parameters, managing cookies, and generating HTML
+# output.
+#
+# The file CGI::Session provides session management functionality; see that
+# class for more details.
+#
+# See http://tools.ietf.org/html/draft-robinson-www-interface-00 for more
+# information on the CGI protocol.
+# =========================================================================== #
+
+# =========================================================================== #
+# == Introduction
+#
+# CGI is a large class, providing several categories of methods, many of which
+# are mixed in from other modules.  Some of the documentation is in this class,
+# some in the modules CGI::QueryExtension and CGI::HtmlExtension.  See
+# CGI::Cookie for specific information on handling cookies, and cgi/session.rb
+# (CGI::Session) for information on sessions.
+#
+# For queries, CGI provides methods to get at environmental variables,
+# parameters, cookies, and multipart request data.  For responses, CGI provides
+# methods for writing output and generating HTML.
+#
+# Read on for more details.  Examples are provided at the bottom.
+# =========================================================================== #
+
+# =========================================================================== #
+# == Queries
+#
+# The CGI class dynamically mixes in parameter and cookie-parsing
+# functionality, environmental variable access, and support for
+# parsing multipart requests (including uploaded files) from the
+# CGI::QueryExtension module.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Environmental Variables
+#
+# The standard CGI environmental variables are available as read-only
+# attributes of a CGI object.
+#
+# The following is a list of these variables, also available in the file
+# constants.rb:
+#
+#   AUTH_TYPE               HTTP_HOST          REMOTE_IDENT
+#   CONTENT_LENGTH          HTTP_NEGOTIATE     REMOTE_USER
+#   CONTENT_TYPE            HTTP_PRAGMA        REQUEST_METHOD
+#   GATEWAY_INTERFACE       HTTP_REFERER       SCRIPT_NAME
+#   HTTP_ACCEPT             HTTP_USER_AGENT    SERVER_NAME
+#   HTTP_ACCEPT_CHARSET     PATH_INFO          SERVER_PORT
+#   HTTP_ACCEPT_ENCODING    PATH_TRANSLATED    SERVER_PROTOCOL
+#   HTTP_ACCEPT_LANGUAGE    QUERY_STRING       SERVER_SOFTWARE
+#   HTTP_CACHE_CONTROL      REMOTE_ADDR
+#   HTTP_FROM               REMOTE_HOST
+#
+# For each of these variables, there is a corresponding attribute with the
+# same name, except all lower case and without a preceding HTTP_.
+# +content_length+ and +server_port+ are integers; the rest are strings.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Parameters
+#
+# The method #params() returns a hash of all parameters in the request as
+# name/value-list pairs, where the value-list is an Array of one or more
+# values.
+#
+# The CGI object itself also behaves as a hash of parameter names to
+# values, but only returns a single value (as a String) for each
+# parameter name.
+#
+# For instance, suppose the request contains the parameter
+# "favourite_colours" with the multiple values "blue" and "green".  The
+# following behaviour would occur:
+#
+#   cgi.params["favourite_colours"]  # => ["blue", "green"]
+#   cgi["favourite_colours"]         # => "blue"
+#
+# If a parameter does not exist, the former method will return an empty
+# array, the latter an empty string. The simplest way to test for
+# existence of a parameter is by the #has_key? method.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Cookies
+#
+# HTTP Cookies are automatically parsed from the request. They are available
+# from the #cookies() accessor, which returns a hash from cookie name to
+# CGI::Cookie object.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Multipart requests
+#
+# If a request's method is POST and its content type is multipart/form-data,
+# then it may contain uploaded files.  These are stored by the QueryExtension
+# module in the parameters of the request.  The parameter name is the name
+# attribute of the file input field, as usual.  However, the value is not
+# a string, but an IO object, either an IOString for small files, or a
+# Tempfile for larger ones.  This object also has the additional singleton
+# methods:
+#
+# #local_path():: the path of the uploaded file on the local filesystem
+# #original_filename():: the name of the file on the client computer
+# #content_type():: the content type of the file
+# =========================================================================== #
+
+# =========================================================================== #
+# == Responses
+#
+# The CGI class provides methods for sending header and content output to
+# the HTTP client, and mixes in methods for programmatic HTML generation
+# from CGI::HtmlExtension and CGI::TagMaker modules.  The precise version
+# of HTML to use for HTML generation is specified at object creation time.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Writing output
+#
+# The simplest way to send output to the HTTP client is using the #out()
+# method. This takes the HTTP headers as a hash parameter, and the body
+# content via a block. The headers can be generated as a string using
+# the #http_header() method. The output stream can be written directly
+# to using the #print() method.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Generating HTML
+#
+# Each HTML element has a corresponding method for generating that
+# element as a String.  The name of this method is the same as that
+# of the element, all lowercase.  The attributes of the element are
+# passed in as a hash, and the body as a no-argument block that evaluates
+# to a String.  The HTML generation module knows which elements are
+# always empty, and silently drops any passed-in body.  It also knows
+# which elements require matching closing tags and which don't.  However,
+# it does not know what attributes are legal for which elements.
+#
+# There are also some additional HTML generation methods mixed in from
+# the CGI::HtmlExtension module.  These include individual methods for the
+# different types of form inputs, and methods for elements that commonly
+# take particular attributes where the attributes can be directly specified
+# as arguments, rather than via a hash.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Utility HTML escape and other methods like a function.
+#
+# There are some utility tool defined in cgi/util.rb .
+# And when include, you can use utility methods like a function.
+#
+# == Examples of use
+#
+# === Get form values
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   value = cgi['field_name']   # <== value string for 'field_name'
+#     # if not 'field_name' included, then return "".
+#   fields = cgi.keys            # <== array of field names
+#
+#   # returns true if form has 'field_name'
+#   cgi.has_key?('field_name')
+#   cgi.has_key?('field_name')
+#   cgi.include?('field_name')
+#
+# CAUTION! cgi['field_name'] returned an Array with the old
+# cgi.rb(included in Ruby 1.6)
+# =========================================================================== #
+
+# =========================================================================== #
+# === Get form values as hash
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   params = cgi.params
+#
+# cgi.params is a hash.
+#
+#   cgi.params['new_field_name'] = ["value"]  # add new param
+#   cgi.params['field_name'] = ["new_value"]  # change value
+#   cgi.params.delete('field_name')           # delete param
+#   cgi.params.clear                          # delete all params
+#
+# =========================================================================== #
+
+# =========================================================================== #
+# === Save form values to file
+#
+#   require "pstore"
+#   db = PStore.new("query.db")
+#   db.transaction do
+#     db["params"] = cgi.params
+#   end
+#
+# =========================================================================== #
+
+# =========================================================================== #
+# === Restore form values from file
+#
+#   require "pstore"
+#   db = PStore.new("query.db")
+#   db.transaction do
+#     cgi.params = db["params"]
+#   end
+#
+# =========================================================================== #
+
+# =========================================================================== #
+# === Get multipart form values
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   value = cgi['field_name']   # <== value string for 'field_name'
+#   value.read                  # <== body of value
+#   value.local_path            # <== path to local file of value
+#   value.original_filename     # <== original filename of value
+#   value.content_type          # <== content_type of value
+#
+# and value has StringIO or Tempfile class methods.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Get cookie values
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   values = cgi.cookies['name']  # <== array of 'name'
+#     # if not 'name' included, then return [].
+#   names = cgi.cookies.keys      # <== array of cookie names
+#
+# and cgi.cookies is a hash.
+# =========================================================================== #
+
+# =========================================================================== #
+# === Get cookie objects
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   for name, cookie in cgi.cookies
+#     cookie.expires = Time.now + 30
+#   end
+#   cgi.out("cookie" => cgi.cookies) {"string"}
+#
+#   cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
+#
+#   require "cgi"
+#   cgi = CGI.new
+#   cgi.cookies['name'].expires = Time.now + 30
+#   cgi.out("cookie" => cgi.cookies['name']) {"string"}
+# =========================================================================== #
+
+# =========================================================================== #
+# === Print http header and html string to $DEFAULT_OUTPUT ($>)
+#
+#   require 'cgi'
+#   cgi = CGI.new("html4")  # add HTML generation methods
+#   cgi.out do
+#     cgi.html do
+#       cgi.head do
+#         cgi.title { "TITLE" }
+#       end +
+#       cgi.body do
+#         cgi.form("ACTION" => "uri") do
+#           cgi.p do
+#             cgi.textarea("get_text") +
+#             cgi.br +
+#             cgi.submit
+#           end
+#         end +
+#         cgi.pre do
+#           CGI.escape_html(
+#             "params: #{cgi.params.inspect}\n" +
+#             "cookies: #{cgi.cookies.inspect}\n" +
+#             ENV.map { |key, value|
+#               "#{key} --> #{value}\n"
+#             }.join("")
+#           )
+#         end
+#       end
+#     end
+#   end
+#
+#   # add HTML generation methods
+#   CGI.new("html3")   # html3.2
+#   CGI.new("html4")   # html4.01 (Strict)
+#   CGI.new("html4Tr") # html4.01 Transitional
+#   CGI.new("html4Fr") # html4.01 Frameset
+#   CGI.new("html5")   # html5
+#
+# === Some utility methods
+#
+#   require 'cyberweb/cgi/util.rb'
+#   require 'cyberweb/cgi/util.rb'; CGI.escape_html('Usage: foo "bar" <baz>')
+#
+# === Some utility methods like a function
+#
+#   require 'cyberweb/cgi/util.rb'
+#   include CGI::Util
+#   escapeHTML('Usage: foo "bar" <baz>')
+#   h('Usage: foo "bar" <baz>') # alias
+#
+# =========================================================================== #
+module Cyberweb
+  class CGI; end # Primer.
+end
+
+# =========================================================================== #
+# Cgi-related ruby files:
+# =========================================================================== #
+require 'cyberweb/cgi/core.rb'
+require 'cyberweb/cgi/cookie.rb'
+require 'cyberweb/cgi/mod_ruby_exception_printer.rb'
+
+# =========================================================================== #
+# Autoload the html.rb extension.
+# =========================================================================== #
+Cyberweb::CGI.autoload(:HtmlExtension, 'html.rb')

data/lib/cyberweb/cgi/constants.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module Cyberweb
+
+class CGI # === Cyberweb::CGI
+
+  require 'cyberweb/constants/standalone_constants.rb'
+  require 'cyberweb/constants/http_status_codes.rb'
+
+  # ========================================================================= #
+  # === Cyberweb::CGI::ARRAY_PREDEFINED_CGI_ENV_VARIABLES
+  #
+  # All ENV variables for use in .cgi scripts should be defined here
+  # prior to their usage.
+  #
+  # SCRIPT_NAME will hold the name of the file that is supposed
+  # to be served to the visitor.
+  # ========================================================================= #
+  ARRAY_PREDEFINED_CGI_ENV_VARIABLES = %w(
+
+    AUTH_TYPE
+    CONTENT_TYPE
+    GATEWAY_INTERFACE
+    HTTP_ACCEPT
+    HTTP_ACCEPT_CHARSET
+    HTTP_ACCEPT_ENCODING
+    HTTP_ACCEPT_LANGUAGE
+    HTTP_CACHE_CONTROL
+    HTTP_FROM
+    HTTP_HOST
+    HTTP_NEGOTIATE
+    HTTP_PRAGMA
+    HTTP_REFERER
+    HTTP_USER_AGENT
+    PATH_INFO
+    PATH_TRANSLATED
+    QUERY_STRING
+    REMOTE_ADDR
+    REMOTE_HOST
+    REMOTE_IDENT
+    REMOTE_USER
+    REQUEST_METHOD
+    SCRIPT_NAME
+    SERVER_NAME
+    SERVER_PROTOCOL
+    SERVER_SOFTWARE
+
+  )
+
+  # ========================================================================= #
+  # === RFC822_MONTHS
+  # ========================================================================= #
+  RFC822_MONTHS = ::Cyberweb::RFC822_MONTHS
+
+  # ========================================================================= #
+  # === RFC822_DAYS
+  # ========================================================================= #
+  RFC822_DAYS = ::Cyberweb::RFC822_DAYS
+
+  # ========================================================================= #
+  # === CR
+  # ========================================================================= #
+  CR  = ::Cyberweb::CR
+
+  # ========================================================================= #
+  # === LF
+  # ========================================================================= #
+  LF  = ::Cyberweb::LF
+
+  # ========================================================================= #
+  # === EOL
+  #
+  # Standard internet newline sequence
+  # ========================================================================= #
+  EOL = ::Cyberweb::EOL
+
+  # ========================================================================= #
+  # === REVISION
+  #
+  # CGI-internal revision.
+  # ========================================================================= #
+  REVISION = '03 Aug 2018'
+
+  # ========================================================================= #
+  # === NEEDS_BINMODE
+  #
+  # Whether processing will be required in binary vs text
+  # ========================================================================= #
+  NEEDS_BINMODE = File::BINARY != 0
+
+  # ========================================================================= #
+  # === HTTP_STATUS
+  #
+  # HTTP status codes are defined here.
+  #
+  # They can be used through this hash here such as:
+  #
+  #   HTTP_STATUS['OK'] # gives '200 OK'.
+  #
+  # ========================================================================= #
+  HTTP_STATUS = ::Cyberweb::HTTP_STATUS
+
+  # ========================================================================= #
+  # === Cyberweb::CGI.predefined_cgi_env_variables
+  # ========================================================================= #
+  def self.predefined_cgi_env_variables
+    ARRAY_PREDEFINED_CGI_ENV_VARIABLES
+  end
+
+end
+
+# =========================================================================== #
+# === Cyberweb.environment?
+# =========================================================================== #
+def self.environment?
+  ::Cyberweb::CGI.predefined_cgi_env_variables
+end
+
+end

data/lib/cyberweb/cgi/cookie.rb

@@ -0,0 +1,218 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Cyberweb::CGI::Cookie
+#
+# The Cookie Class represents a HTTP cookie.
+#
+# In addition to its specific fields and methods, a Cookie
+# instance is a delegator to the array of its values.
+#
+# See RFC 2965.
+#
+# == Usage examples:
+#
+#   cookie1 = CGI::Cookie.new("name", "value1", "value2", ...)
+#   cookie1 = CGI::Cookie.new("name" => "name", "value" => "value")
+#   cookie1 = CGI::Cookie.new('name'    => 'name',
+#                              'value'   => ['value1', 'value2', ...],
+#                              'path'    => 'path',   # optional
+#                              'domain'  => 'domain', # optional
+#                              'expires' => Time.now, # optional
+#                              'secure'  => true      # optional
+#                             )
+#
+#   cgi.out("cookie" => [cookie1, cookie2]) { "string" }
+#
+#   name    = cookie1.name
+#   values  = cookie1.value
+#   path    = cookie1.path
+#   domain  = cookie1.domain
+#   expires = cookie1.expires
+#   secure  = cookie1.secure
+#
+#   cookie1.name    = 'name'
+#   cookie1.value   = ['value1', 'value2', ...]
+#   cookie1.path    = 'path'
+#   cookie1.domain  = 'domain'
+#   cookie1.expires = Time.now + 30
+#   cookie1.secure  = true
+# =========================================================================== #
+# The cookie-part depends on the file util.rb
+# =========================================================================== #
+module Cyberweb
+
+class CGI
+
+require 'cyberweb/cgi/util.rb'
+
+  class Cookie < Array # === Cyberweb::CGI::Cookie
+
+    @@accept_charset = 'UTF-8' unless defined? @@accept_charset
+
+    # ======================================================================= #
+    # Name of this cookie, as a +String+.
+    # ======================================================================= #
+    attr_accessor :name
+    # ======================================================================= #
+    # The path for which this cookie applies, as a +String+
+    # ======================================================================= #
+    attr_accessor :path
+    # ======================================================================= #
+    # Domain for which this cookie applies, as a +String+
+    # ======================================================================= #
+    attr_accessor :domain
+    # ======================================================================= #
+    # Time at which this cookie expires, as a +Time+
+    # ======================================================================= #
+    attr_accessor :expires
+    # ======================================================================= #
+    # True if this cookie is secure; false otherwise
+    # ======================================================================= #
+    attr_reader :secure
+
+    # ======================================================================= #
+    # === initialize
+    #
+    # Create a new CGI::Cookie object.
+    #
+    # :call-seq:
+    #   Cookie.new(name_string,*value)
+    #   Cookie.new(options_hash)
+    #
+    # +name_string+::
+    #   The name of the cookie; in this form, there is no #domain or
+    #   #expiration.  The #path is gleaned from the +SCRIPT_NAME+ environment
+    #   variable, and #secure is false.
+    # <tt>*value</tt>::
+    #   value or list of values of the cookie
+    # +options_hash+::
+    #   A Hash of options to initialize this Cookie.  Possible options are:
+    #
+    #   name:: the name of the cookie.  Required.
+    #   value:: the cookie's value or list of values.
+    #   path:: the path for which this cookie applies.  Defaults to the
+    #          the value of the +SCRIPT_NAME+ environment variable.
+    #   domain:: the domain for which this cookie applies.
+    #   expires:: the time at which this cookie expires, as a +Time+ object.
+    #   secure:: whether this cookie is a secure cookie or not (default to
+    #            false).  Secure cookies are only transmitted to HTTPS
+    #            servers.
+    #
+    #   These keywords correspond to attributes of the cookie object.
+    # ======================================================================= #
+    def initialize(
+        name = '', *value
+      )
+      @domain = nil
+      @expires = nil
+      if name.is_a? String
+        @name = name
+        %r|^(.*/)|.match(ENV['SCRIPT_NAME'])
+        @path = ($1 or '')
+        @secure = false
+        return super(value)
+      end
+
+      options = name
+      unless options.has_key? 'name'
+        raise ArgumentError, "`name' required"
+      end
+
+      @name = options['name']
+      value = Array(options["value"])
+      # simple support for IE
+      if options['path']
+        @path = options['path']
+      else
+        %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
+        @path = ($1 or "")
+      end
+      @domain  = options['domain']
+      @expires = options['expires']
+      @secure  = options['secure'] == true ? true : false
+      super(value)
+    end
+
+    # ======================================================================= #
+    # === value
+    #
+    # Returns the value or list of values for this cookie.
+    # ======================================================================= #
+    def value
+      self
+    end
+
+    # ======================================================================= #
+    # === value=
+    #
+    # Replaces the value of this cookie with a new value or list of values.
+    # ======================================================================= #
+    def value=(i)
+      replace(Array(i))
+    end
+
+    # ======================================================================= #
+    # === secure=
+    #
+    # Set whether the Cookie is a secure cookie or not.
+    #
+    # +val+ must be a boolean.
+    # ======================================================================= #
+    def secure=(i)
+      @secure = i if i == true or i == false
+      @secure # And return it.
+    end
+
+    # ======================================================================= #
+    # === to_s
+    #
+    # Convert the Cookie to its string representation.
+    # ======================================================================= #
+    def to_s
+      val = map {|v| CGI.escape(v) }.join("&")
+      buf = "#{@name}=#{val}"
+      buf << "; domain=#{@domain}" if @domain
+      buf << "; path=#{@path}"     if @path
+      buf << "; expires=#{CGI::rfc1123_date(@expires)}" if @expires
+      buf << "; secure"            if @secure == true
+      buf
+    end
+
+    # ======================================================================= #
+    # === Cookie.parse
+    #
+    # Parse a raw cookie string into a hash of cookie-name=>Cookie pairs.
+    #
+    #   cookies = CGI::Cookie.parse("raw_cookie_string")
+    #     # { "name1" => cookie1, "name2" => cookie2, ... }
+    # ======================================================================= #
+    def self.parse(raw_cookie)
+      cookies = Hash.new([])
+      return cookies unless raw_cookie
+      raw_cookie.split(/[;,]\s?/).each { |pairs|
+        name, values = pairs.split('=', 2)
+        next unless name and values
+        name = CGI.unescape(name)
+        values ||= ''
+        values = values.split('&').map {|v| CGI.unescape(v, @@accept_charset) }
+        if cookies.has_key?(name)
+          values = cookies[name].value + values
+        end
+        cookies[name] = Cookie.new(name, *values)
+      }
+      cookies
+    end
+
+    # ======================================================================= #
+    # === inspect
+    #
+    # A summary of the cookie string.
+    # ======================================================================= #
+    def inspect
+      "#<Cyberweb::CGI::Cookie: #{self.to_s.inspect}>"
+    end
+  end # class Cookie
+
+end; end