From 39cdfe21bb0739428e17b75b90d873109c29a55f Mon Sep 17 00:00:00 2001 From: Michael Westbom Date: Fri, 11 Jan 2013 14:39:25 -0500 Subject: [PATCH] Added a whole bunch of yard documentation. --- lib/group.rb | 16 -------- lib/nntp.rb | 25 +++++++++++- lib/nntp/connection.rb | 47 ++++++++++++++++++++++- lib/nntp/session.rb | 35 ++++++++++++++++- NNTPClient.gemspec => nntp-client.gemspec | 2 +- 5 files changed, 105 insertions(+), 20 deletions(-) delete mode 100644 lib/group.rb rename NNTPClient.gemspec => nntp-client.gemspec (95%) diff --git a/lib/group.rb b/lib/group.rb deleted file mode 100644 index e01771c..0000000 --- a/lib/group.rb +++ /dev/null @@ -1,16 +0,0 @@ -module NNTP - class Group - attr_accessor :name, :first, :last, :count - - def initialize(count, first, last, name) - @name = name - @first = first - @last = last - @count = count - end - - def inspect - name - end - end -end \ No newline at end of file diff --git a/lib/nntp.rb b/lib/nntp.rb index db5a57a..fed3b90 100644 --- a/lib/nntp.rb +++ b/lib/nntp.rb @@ -4,7 +4,30 @@ require "nntp/connection" require 'nntp/ssl_connection' +# The main entry point for this module is the open method. +# +# ::open returns an object that is an active NNTP session. +# If a block is passed to it, the session object is made available +# therein. module NNTP + # The main entrypoint to the module. + # + # @option options :url The URL of the NNTP server. + # @option options :port (119/563) The port number of the server. + # @option options [Boolean] :ssl (false) Connect via SSL? + # @option options [Hash] :auth Authentication credentials and style. + # @example Basic connection + # nntp = NNTP.open( + # :url => 'nntp.example.org', + # :auth => {:user => 'mike', :pass => 'soopersecret'} + # ) + # nntp.quit + # @example Pass a block + # # Automatically closes connection + # NNTP.open(:url => 'nntp.example.org') do |nntp| + # nntp.group = 'alt.bin.foo' + # end + # @return [NNTP::Session] the active NNTP session def self.open(options) if options[:ssl] connection = SSLConnection.new(options) @@ -23,4 +46,4 @@ def self.open(options) session end end -end \ No newline at end of file +end diff --git a/lib/nntp/connection.rb b/lib/nntp/connection.rb index 289ac9a..3a2b427 100644 --- a/lib/nntp/connection.rb +++ b/lib/nntp/connection.rb @@ -2,13 +2,51 @@ require 'nntp/status' module NNTP + # Handles communication with the NNTP server. + # + # Most communication with an NNTP server happens in a back-and-forth + # style. + # + # The client sends a message to the server. The server will respond with a status response, and sometimes with extra data. See {https://tools.ietf.org/html/rfc3977 RFC 3977} for more details. + # + # This class handles this communication by providing two methods, + # one for use when additional data is expected, and one for when it is not. class Connection + # @!attribute [r] socket + # The object upon which all IO takes place. + # + # @!attribute [r] status + # The most status of the most recent command. + # @return [NNTP::Status] + attr_reader :socket, :status + # (see #build_socket) def initialize(options) @socket = build_socket(options) end + # Sends a message to the server, collects the the status and additional data, if successful. + # A Hash is returned containing two keys: :status and :data. + # :status is an {NNTP::Status}, and :data is an array containing + # the lines from the response See example for details. + # @example + # nntp.query(:list) do |status, data| + # $stdout.puts status + # data.each? do |line| + # $stdout.puts line + # end + # end + # + # => 215 Information follows + # => alt.bin.foo + # => alt.bin.bar + # @param query [Symbol, String] The command to send + # @param args Any additional parameters are passed along with the command. + # @yield The status and data from the server. + # @yieldparam status [NNTP::Status] + # @yieldparam data [Array, nil] An array with the lines from the server. Nil if the query failed. + # @return [Hash] The status and requested data. def query(query, *args) command = form_message(query, args) send_message(command) @@ -22,17 +60,24 @@ def query(query, *args) {:status => status, :data => data} end + # Sends a message to the server and collects the status response. + # @param (see #query) + # @return [NNTP::Status] The server's response. def command(command, *args) command = form_message(command, args) send_message(command) get_status end + # Fetch a status line from the server. + # @return [NNTP::Status] def get_status code, message = get_line.split(' ', 2) @status = status_factory(code.to_i, message) end + # Sends "QUIT\\r\\n" to the server, disconnects the socket. + # @return [void] def quit command(:quit) socket.close @@ -78,4 +123,4 @@ def status_factory(*args) NNTP::Status.new(*args) end end -end \ No newline at end of file +end diff --git a/lib/nntp/session.rb b/lib/nntp/session.rb index 0b413b9..8c3b0dd 100644 --- a/lib/nntp/session.rb +++ b/lib/nntp/session.rb @@ -2,8 +2,14 @@ require 'nntp/message' module NNTP + # Most of the action happens here. This class describes the + # object the user interacts with the most. + # It is constructed by NNTP::open, but you can build your own + # if you like. class Session attr_reader :connection, :group + # @option options [NNTP::Connection, NNTP::SSLConnection] :connection + # The connection object. def initialize(options) @group = nil @connection = options.fetch(:connection) do @@ -12,15 +18,31 @@ def initialize(options) check_initial_status end + # Authenticate to the server. + # + # @option args :user Username + # @option args :pass Password + # @option args :type (:standard) + # Which authentication type to use. Currently only + # standard is supported. + # @return [NNTP::Status] def auth(args) auth_method = args.fetch(:type, :standard) standard_auth(args) if auth_method == :standard end + # Fetches and returns the list of groups from the server or, if it + # has already been fetched, returns the saved list. + # @return [Array] def groups @groups ||= fetch_groups end + # @!attribute [rw] group + # Retrieves current group, or + # sets current group, server-side, to assigned value. + # @param [String] group_name The name of the group to be selected. + # @return [NNTP::Group] The current group. def group=(group_name) connection.command(:group, group_name) if status[:code] == 211 @@ -29,6 +51,12 @@ def group=(group_name) end end + # Fetch list of message numbers from a given group. + # @param group The name of the group to list defaults to {#group #group.name} + # @param range (nil) If given, specifies the range of messages to retrieve + # @return [Array] The list of messages + # (only the message numbers will be populated). + # @see https://tools.ietf.org/html/rfc3977#section-6.1.2 def listgroup(*args) messages = [] connection.query(:listgroup, *args) do |status, data| @@ -43,6 +71,9 @@ def listgroup(*args) messages end + # Fetch list of messages from current group. + # @return [Array] The list of messages + # (The numbers AND the subjects will be populated). def subjects subjects = [] range ="#{group[:first_message]}-" @@ -58,10 +89,12 @@ def subjects subjects end + # The most recent status from the server. def status connection.status end + # (see NNTP::Connection#quit) def quit connection.quit end @@ -103,4 +136,4 @@ def fetch_groups group_list end end -end \ No newline at end of file +end diff --git a/NNTPClient.gemspec b/nntp-client.gemspec similarity index 95% rename from NNTPClient.gemspec rename to nntp-client.gemspec index 840f205..adf7a41 100644 --- a/NNTPClient.gemspec +++ b/nntp-client.gemspec @@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) require 'nntp/version' Gem::Specification.new do |gem| - gem.name = "nntp" + gem.name = "nntp-client" gem.version = NNTP::VERSION gem.authors = ["Michael Westbom"] gem.email = %w(totallymike@gmail.com)