diff --git a/ChangeLog b/ChangeLog index 3ddeb42084..610a01ef10 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Mon Oct 9 23:46:29 2006 Yukihiro Matsumoto + + * lib/parsedate.rb: documentation patch from Konrad Meyer + . [ruby-doc:1238] + + * lib/open3.rb, lib/ping.rb: ditto. + Mon Oct 9 23:40:58 2006 Nobuyoshi Nakada * ext/extmk.rb, lib/fileutils.rb, lib/mkmf.rb, lib/optparse.rb, diff --git a/lib/open3.rb b/lib/open3.rb index f722252b1c..c4dacc9473 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 +# +# Author:: Yukihiro Matsumoto +# Documentation:: Konrad Meyer +# +# Open3 gives you access to stdin, stdout, and stderr when running other +# programs. +# + +# +# Open3 grants you access to stdin, stdout, and stderr when running another +# program. Example: # # require "open3" -# -# stdin, stdout, stderr = Open3.popen3('nroff -man') -# -# or: -# # 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 405ab46907..b52a79ba47 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 7728ece979..c2966b619c 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 +# +# Ping contains routines to test for the reachability of remote hosts. +# Currently the only routine implemented is pingecho(). # -# require 'ping' -# -# puts "'jimmy' is alive and kicking" if Ping.pingecho('jimmy', 10) -# -#= DESCRIPTION -# -# 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 +# Warning: Ping.pingecho may block for a long time if DNS resolution is +# slow. Requiring 'resolv-replace' allows non-blocking name resolution. # -# pingecho() may block for a long period if name resolution is slow. Require -# 'resolv-replace' to use non-blocking name resolution. +# Usage: +# +# require 'ping' +# +# 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