summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-10-09 14:49:49 +0000
committermatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-10-09 14:49:49 +0000
commitbb9f40a725e780c279ebcc908fc39084d8bd2545 (patch)
treef899cdae77850820e17d14e7e0536e646edea623
parent88d6c083ea969b5e7b24315fd612958755afcc54 (diff)
* lib/parsedate.rb: documentation patch from Konrad Meyer
<konrad.meyer@gmail.com>. [ruby-doc:1238] * lib/open3.rb, lib/ping.rb: ditto. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@11113 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--ChangeLog7
-rw-r--r--lib/open3.rb45
-rw-r--r--lib/parsedate.rb44
-rw-r--r--lib/ping.rb49
4 files changed, 110 insertions, 35 deletions
diff --git a/ChangeLog b/ChangeLog
index 3ddeb42084a..610a01ef10f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Mon Oct 9 23:46:29 2006 Yukihiro Matsumoto <matz@ruby-lang.org>
+
+ * lib/parsedate.rb: documentation patch from Konrad Meyer
+ <konrad.meyer@gmail.com>. [ruby-doc:1238]
+
+ * lib/open3.rb, lib/ping.rb: ditto.
+
Mon Oct 9 23:40:58 2006 Nobuyoshi Nakada <nobu@ruby-lang.org>
* ext/extmk.rb, lib/fileutils.rb, lib/mkmf.rb, lib/optparse.rb,
diff --git a/lib/open3.rb b/lib/open3.rb
index f722252b1c8..c4dacc9473a 100644
--- a/lib/open3.rb
+++ b/lib/open3.rb
@@ -1,29 +1,48 @@
-# open3.rb: Spawn a program like popen, but with stderr, too. You might also
-# want to use this if you want to bypass the shell. (By passing multiple args,
-# which IO#popen does not allow)
#
-# Usage:
+# = open3.rb: Popen, but with stderr, too
#
-# require "open3"
-#
-# stdin, stdout, stderr = Open3.popen3('nroff -man')
+# Author:: Yukihiro Matsumoto
+# Documentation:: Konrad Meyer
+#
+# Open3 gives you access to stdin, stdout, and stderr when running other
+# programs.
+#
+
#
-# or:
+# Open3 grants you access to stdin, stdout, and stderr when running another
+# program. Example:
#
+# require "open3"
# include Open3
#
# stdin, stdout, stderr = popen3('nroff -man')
#
-# popen3 can also take a block which will receive stdin, stdout and stderr as
-# parameters. This ensures stdin, stdout and stderr are closed once the block
-# exits.
+# Open3.popen3 can also take a block which will receive stdin, stdout and
+# stderr as parameters. This ensures stdin, stdout and stderr are closed
+# once the block exits. Example:
#
-# Such as:
+# require "open3"
#
# Open3.popen3('nroff -man') { |stdin, stdout, stderr| ... }
+#
module Open3
- #[stdin, stdout, stderr] = popen3(command);
+ #
+ # Open stdin, stdout, and stderr streams and start external executable.
+ # Non-block form:
+ #
+ # require 'open3'
+ #
+ # [stdin, stdout, stderr] = Open3.popen3(cmd)
+ #
+ # Block form:
+ #
+ # require 'open3'
+ #
+ # Open3.popen3(cmd) { |stdin, stdout, stderr| ... }
+ #
+ # The parameter +cmd+ is passed directly to Kernel#exec.
+ #
def popen3(*cmd)
pw = IO::pipe # pipe[0] for read, pipe[1] for write
pr = IO::pipe
diff --git a/lib/parsedate.rb b/lib/parsedate.rb
index 405ab469078..b52a79ba47a 100644
--- a/lib/parsedate.rb
+++ b/lib/parsedate.rb
@@ -1,10 +1,48 @@
-# parsedate.rb: Written by Tadayoshi Funaba 2001, 2002
-# $Id: parsedate.rb,v 2.6 2002-05-14 07:43:18+09 tadf Exp $
+#
+# = parsedate.rb: Parses dates
+#
+# Author:: Tadayoshi Funaba
+# Documentation:: Konrad Meyer
+#
+# ParseDate munches on a date and turns it into an array of values.
+#
+
+#
+# ParseDate converts a date into an array of values.
+# For example:
+#
+# require 'parsedate'
+#
+# ParseDate.parsedate "Tuesday, July 6th, 2007, 18:35:20 UTC"
+# # => [2007, 7, 6, 18, 35, 20, "UTC", 2]
+#
+# The order is of the form [year, month, day of month, hour, minute, second,
+# timezone, day of the week].
require 'date/format'
module ParseDate
-
+ #
+ # Parse a string representation of a date into values.
+ # For example:
+ #
+ # require 'parsedate'
+ #
+ # ParseDate.parsedate "Tuesday, July 5th, 2007, 18:35:20 UTC"
+ # # => [2007, 7, 5, 18, 35, 20, "UTC", 2]
+ #
+ # The order is of the form [year, month, day of month, hour, minute,
+ # second, timezone, day of week].
+ #
+ # ParseDate.parsedate can also take a second argument, +comp+, which
+ # is a boolean telling the method to compensate for dates with years
+ # expressed as two digits. Example:
+ #
+ # require 'parsedate'
+ #
+ # ParseDate.parsedate "Mon Dec 25 00 06:53:24 UTC", true
+ # # => [2000, 12, 25, 6, 53, 24, "UTC", 1]
+ #
def parsedate(str, comp=false)
Date._parse(str, comp).
values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :wday)
diff --git a/lib/ping.rb b/lib/ping.rb
index 7728ece9797..c2966b619c0 100644
--- a/lib/ping.rb
+++ b/lib/ping.rb
@@ -1,35 +1,46 @@
#
-# ping.rb -- check a host for upness
+# = ping.rb: Check a host for upness
+#
+# Author:: Yukihiro Matsumoto
+# Documentation:: Konrad Meyer
+#
+# Performs the function of the basic network testing tool, ping.
+# See: Ping.
#
require 'timeout'
require "socket"
-#= SYNOPSIS
-#
-# require 'ping'
-#
-# puts "'jimmy' is alive and kicking" if Ping.pingecho('jimmy', 10)
-#
-#= DESCRIPTION
+#
+# Ping contains routines to test for the reachability of remote hosts.
+# Currently the only routine implemented is pingecho().
#
-# This module contains routines to test for the reachability of remote hosts.
-# Currently the only routine implemented is pingecho().
-#
-# pingecho() uses a TCP echo (_not_ an ICMP echo) to determine if the
+# Ping.pingecho uses a TCP echo (not an ICMP echo) to determine if the
# remote host is reachable. This is usually adequate to tell that a remote
-# host is available to rsh(1), ftp(1), or telnet(1) to.
+# host is available to telnet, ftp, or ssh to.
+#
+# Warning: Ping.pingecho may block for a long time if DNS resolution is
+# slow. Requiring 'resolv-replace' allows non-blocking name resolution.
#
-#= WARNING
+# Usage:
+#
+# require 'ping'
#
-# pingecho() may block for a long period if name resolution is slow. Require
-# 'resolv-replace' to use non-blocking name resolution.
+# puts "'jimmy' is alive and kicking" if Ping.pingecho('jimmy', 10)
#
module Ping
- # return true if we can open a connection to the hostname or IP address
- # +host+ on port +service+ (which defaults to the "echo" port) waiting up to
- # +timeout+ seconds.
+ #
+ # Return true if we can open a connection to the hostname or IP address
+ # +host+ on port +service+ (which defaults to the "echo" port) waiting up
+ # to +timeout+ seconds.
+ #
+ # Example:
+ #
+ # require 'ping'
+ #
+ # Ping.pingecho "google.com", 10, 80
+ #
def pingecho(host, timeout=5, service="echo")
begin
timeout(timeout) do