ezid-client 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c103eaae29bd61679e4e349a5a14ab7964edd291
-  data.tar.gz: 047f1df3708982722bcbad3fac050183cf6285a6
+  metadata.gz: 7c3a0edbc74bbd749bf0c099fa07cad69bfebcdb
+  data.tar.gz: 4fdea290531b0f68d4d652a17b800585a4514f34
 SHA512:
-  metadata.gz: 53b9aa4362dbeea70ad165b6977756b63ac0ca6ad970fae98caa11ba135e83603f102b23de54b27577a38293f3701bf89712bdc60e7fd19409de0dc1f9a2ea73
-  data.tar.gz: ac9b5fa24406b489ce716d6683d2d68c2d6c7e01d59da813e1848385f811ce3d9f4158e6e3b8649935c216624fb273742097bf639d181af7c8a5c04a828cff61
+  metadata.gz: 8eecfcf10284ab9c6ccbe0916547d704d75ee3b0e9b8d6da0ff4dcadbe35a3d698400f741483c5529f6ce1809caee462b812d76356231ac06732d3ebbac49f7f
+  data.tar.gz: 0c137cf93d57cff8186821ace6125ca390833ed8a07327d1cffb50e708a8dae374594e374fe3f2cd603e725295b8e0c367645cb3639c568ca230e48814f3b01d

data/README.md

@@ -16,51 +16,109 @@ Or install it yourself as:
 
     $ gem install ezid-client
 
-## Usage
+## Basic Usage
 
-Create a client
+See `Ezid::Client` class for details.
 
-```ruby
->> client = Ezid::Client.new(user: "apitest", password: "********")
-=> #<Ezid::Client:0x007f857c23ca40 @user="apitest", @password="********", @session=#<Ezid::Session:0x007f857c2515a8 @cookie="sessionid=quyclw5bbnwsay0qh05isalt86xj5o1l">>
+**Create a client**
+
+```
+>> client = Ezid::Client.new(user: "apitest")
+=> #<Ezid::Client:0x007f8ce651a890 , @user="apitest", @password="********">
 ```
 
-Mint an identifier
+Initialize with a block (wraps in a session)
 
-```ruby
->> response = client.mint_identifier("ark:/99999/fk4")
-=> #<Ezid::Response:0x007f857c488010 @http_response=#<Net::HTTPCreated 201 CREATED readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c488448 @elements={}>, @result="success", @message="ark:/99999/fk4988cc8j">
->> response.identifier
-=> "ark:/99999/fk4988cc8j"
+```
+>> Ezid::Client.new(user: "apitest") do |client|
+?>   client.server_status("*")
+>> end
+I, [2014-11-20T13:23:23.120797 #86059]  INFO -- : success: session cookie returned
+I, [2014-11-20T13:23:25.336596 #86059]  INFO -- : success: EZID is up
+I, [2014-11-20T13:23:25.804790 #86059]  INFO -- : success: authentication credentials flushed
+=> #<Ezid::Client:0x007faa5a6a9ee0 , @user="apitest", @password="********">
 ```
 
-Modify identifier metadata
+**Login**
 
-```ruby
->> metadata = Ezid::Metadata.new("dc.type" => "Image")
-=> #<Ezid::Metadata:0x007f857c251c88 @elements={"dc.type"=>"Image"}>
->> response = client.modify_identifier("ark:/99999/fk4988cc8j", metadata)
-=> #<Ezid::Response:0x007f857c53ab20 @http_response=#<Net::HTTPOK 200 OK readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c53aa30 @elements={}>, @result="success", @message="ark:/99999/fk4988cc8j">
+Note that login is not required to send authenticated requests; it merely establishes a session.  See http://ezid.cdlib.org/doc/apidoc.html#authentication.
+
+```
+>> client.login
+I, [2014-11-20T13:10:50.958378 #85954]  INFO -- : success: session cookie returned
+=> #<Ezid::Client:0x007f8ce651a890 LOGGED_IN, @user="apitest", @password="********">
 ```
 
-Get identifier metadata
+**Mint an identifier**
 
 ```
->> response = client.get_identifier_metadata("ark:/99999/fk4988cc8j")
-=> #<Ezid::Response:0x007f857c50a060 @http_response=#<Net::HTTPOK 200 OK readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c509f48 @elements={"_updated"=>"1416436386", "_target"=>"http://ezid.cdlib.org/id/ark:/99999/fk4988cc8j", "_profile"=>"erc", "dc.type"=>"Image", "_ownergroup"=>"apitest", "_owner"=>"apitest", "_export"=>"yes", "_created"=>"1416436287", "_status"=>"public"}>, @result="success", @message="ark:/99999/fk4988cc8j">
->> response.metadata["dc.type"]
-=> "Image"
+>> response = client.mint_identifier("ark:/99999/fk4")
+I, [2014-11-20T13:11:25.894128 #85954]  INFO -- : success: ark:/99999/fk4fn19h87
+=> #<Net::HTTPCreated 201 CREATED readbody=true>
+>> response.identifier
+=> "ark:/99999/fk4fn19h87"
+```
+
+**Get identifier metadata**
+
+```
+>> response = client.get_identifier_metadata(response.identifier)
+I, [2014-11-20T13:12:08.700287 #85954]  INFO -- : success: ark:/99999/fk4fn19h87
+=> #<Net::HTTPOK 200 OK readbody=true>
 >> puts response.metadata
-_updated: 1416436386
-_target: http://ezid.cdlib.org/id/ark:/99999/fk4988cc8j
+_updated: 1416507086
+_target: http://ezid.cdlib.org/id/ark:/99999/fk4fn19h87
 _profile: erc
-dc.type: Image
 _ownergroup: apitest
 _owner: apitest
 _export: yes
-_created: 1416436287
+_created: 1416507086
 _status: public
+=> nil
+```
+
+**Logout**
+
 ```
+>> client.logout
+I, [2014-11-20T13:18:47.213566 #86059]  INFO -- : success: authentication credentials flushed
+=> #<Ezid::Client:0x007faa5a712350 , @user="apitest", @password="********">
+```
+
+## Resource-oriented Usage
+
+Experimental -- see `Ezid::Identifier`.
+
+## Metadata handling
+
+See `Ezid::Metadata`.
+
+## Authentication
+
+Credentials can be provided in any -- or a combination -- of these ways:
+
+- Environment variables `EZID_USER` and/or `EZID_PASSWORD`;
+
+- Client configuration:
+
+```ruby
+Ezid::Client.configure do |config|
+  config.user = "eziduser"
+  config.password = "ezidpass"
+end
+```
+
+- At client initialization:
+
+```ruby
+client = Ezid::Client.new(user: "eziduser", password: "ezidpass")
+```
+
+## Running the tests
+
+By default the tests authenticate as user "apitest"; the password is not provided -- see http://ezid.cdlib.org/doc/apidoc.html#testing-the-api.
+
+The test suite uses [VCR](https://relishapp.com/vcr/vcr) and [WebMock](https://github.com/bblimke/webmock) to stub requests and responses after the first run.  The VCR "cassettes" are written to `spec/cassettes` and may be cleared with the rake task `test:clean`.
 
 ## Contributing
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/ezid/api.rb

@@ -2,47 +2,62 @@ module Ezid
   #
   # EZID API Version 2 bindings
   #
+  # @api private
   module Api
 
     VERSION = "2"
 
     # EZID server subsystems
-    DATACITE_SUBSYSTEM = "datacite"
-    NOID_SUBSYSTEM = "noid"
-    LDAP_SUBSYSTEM = "ldap"
-    ALL_SUBSYSTEMS = "*"
+    # "*" = all subsystems
+    SUBSYSTEMS = %w( datacite noid ldap * )
 
     class << self
-
+      
+      # Start a session
+      # @see http://ezid.cdlib.org/doc/apidoc.html#authentication
       def login
         [:Get, "/login"]
       end
 
+      # End the current session
+      # @see http://ezid.cdlib.org/doc/apidoc.html#authentication
       def logout
         [:Get, "/logout"]
       end
 
+      # Operation: mint identifier
+      # @see http://ezid.cdlib.org/doc/apidoc.html#operation-mint-identifier
       def mint_identifier(shoulder)
         [:Post, "/shoulder/#{shoulder}"]
       end
 
+      # Operation: create identifier
+      # @see http://ezid.cdlib.org/doc/apidoc.html#operation-create-identifier
       def create_identifier(identifier)
         [:Put, "/id/#{identifier}"]
       end
 
+      # Operation: modify identifier
+      # @see http://ezid.cdlib.org/doc/apidoc.html#operation-modify-identifier
       def modify_identifier(identifier)
         [:Post, "/id/#{identifier}"]
       end
 
+      # Operation: get identifier metadata
+      # @see http://ezid.cdlib.org/doc/apidoc.html#operation-get-identifier-metadata
       def get_identifier_metadata(identifier)
         [:Get, "/id/#{identifier}"]
       end
 
+      # Operation: delete identifier
+      # @see http://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier
       def delete_identifier(identifier)
         [:Delete, "/id/#{identifier}"]
       end
 
-      def server_status(subsystems)
+      # Probe EZID server status
+      # @see http://ezid.cdlib.org/doc/apidoc.html#server-status
+      def server_status(*subsystems)
         [:Get, "/status", "subsystems=#{subsystems.join(',')}"]
       end
 

data/lib/ezid/client.rb

@@ -1,33 +1,52 @@
+require_relative "api"
 require_relative "identifier"
 require_relative "request"
+require_relative "response"
+require_relative "metadata"
 require_relative "session"
 require_relative "configuration"
 require_relative "error"
+require_relative "logger"
 
 module Ezid
+  #
+  # EZID client
+  #
+  # @api public
   class Client
 
     class << self
+      # Configuration reader
       def config
         @config ||= Configuration.new
       end
-
+      
+      # Yields the configuration to a block
+      # @yieldparam [Ezid::Configuration] the configuration
       def configure
         yield config
       end
 
+      # Creates an new identifier
+      # @see #create_identifier
       def create_identifier(*args)
         Client.new.create_identifier(*args)
       end
 
+      # Mints a new identifier
+      # @see #mint_identifier
       def mint_identifier(*args)
         Client.new.mint_identifier(*args)
       end
-
+      
+      # Retrieve the metadata for an identifier
+      # @see #get_identifier_metadata
       def get_identifier_metadata(*args)
         Client.new.get_identifier_metadata(*args)
       end
 
+      # Logs into EZID
+      # @see #login
       def login
         Client.new.login
       end
@@ -53,131 +72,144 @@ module Ezid
       out
     end
 
+    # The client configuration
+    # @return [Ezid::Configuration] the configuration object
     def config
       self.class.config
     end
 
+    # The client logger
+    # @return [Ezid::Logger] the logger
     def logger
-      config.logger
+      @logger ||= Ezid::Logger.new(config.logger)
     end
 
+    # Open a session
+    # @return [Ezid::Client] the client
     def login
       if logged_in?
         logger.info("Already logged in, skipping login request.")
       else
         do_login
       end
+      self
     end
 
+    # Close the session
+    # @return [Ezid::Client] the client
     def logout
       if logged_in?
         do_logout
       else
         logger.info("Not logged in, skipping logout request.")
       end
+      self
     end
 
+    # @return [true, false] whether the client is logged in
     def logged_in?
       session.open?
     end
 
+    # @param identifier [String] the identifier string to create
+    # @param metadata [String, Hash, Ezid::Metadata] optional metadata to set
+    # @return [Ezid::Response] the response
     def create_identifier(identifier, metadata=nil)
-      request = Request.build(:create_identifier, identifier)
+      request = Request.new(:create_identifier, identifier)
       add_authentication(request)
       add_metadata(request, metadata)
       execute(request)
     end
 
+    # @param shoulder [String] the shoulder on which to mint a new identifier
+    # @param metadata [String, Hash, Ezid::Metadata] metadata to set
+    # @return [Ezid::Response] the response
     def mint_identifier(shoulder, metadata=nil)
-      request = Request.build(:mint_identifier, shoulder)
+      request = Request.new(:mint_identifier, shoulder)
       add_authentication(request)
       add_metadata(request, metadata)
       execute(request)
     end
     
+    # @param identifier [String] the identifier to modify
+    # @param metadata [String, Hash, Ezid::Metadata] metadata to set
+    # @return [Ezid::Response] the response
     def modify_identifier(identifier, metadata)
-      raise ArgumentError, "Metadata is required" if metadata.nil? || metadata.empty?
-      request = Request.build(:modify_identifier, identifier)
+      request = Request.new(:modify_identifier, identifier)
       add_authentication(request)
       add_metadata(request, metadata)
       execute(request)
     end
 
+    # @param identifier [String] the identifier to retrieve
+    # @return [Ezid::Response] the response
     def get_identifier_metadata(identifier)
-      request = Request.build(:get_identifier_metadata, identifier)
+      request = Request.new(:get_identifier_metadata, identifier)
       add_authentication(request)
       execute(request)
     end
 
+    # @param identifier [String] the identifier to delete
+    # @return [Ezid::Response] the response
     def delete_identifier(identifier)
-      request = Request.build(:delete_identifier, identifier)
+      request = Request.new(:delete_identifier, identifier)
       add_authentication(request)
       execute(request)
     end
 
+    # @param subsystems [Array]
+    # @return [Ezid::Response] the response
     def server_status(*subsystems)
-      request = Request.build(:server_status, subsystems)
+      request = Request.new(:server_status, *subsystems)
       execute(request)
     end
 
     private
 
-    # Executes the request
-    def execute(request)
-      response = request.execute
-      handle_response(response)
+    def build_request(*args)
+      request = Request.new(*args)
     end
 
-    # Handles the response
-    def handle_response(response)
+    # Executes the request
+    # @param request [Ezid::Request] the request
+    # @raise [Ezid::Error] if the response status indicates an error
+    # @return [Ezid::Response] the response
+    def execute(request)
+      response = Response.new(request.execute)
+      logger.request_and_response(request, response)
       raise Error, response.message if response.error?
       response
-    ensure
-      log_response(response)
-    end
-
-    # Logs a message for the response
-    def log_response(response)
-      logger.log(log_level(response), log_message(response))
-    end
-
-    # Returns the log level to use for the response
-    def log_level(response)
-      response.error? ? Logger::ERROR : Logger::INFO
-    end
-
-    # Returns the message to log for the response
-    def log_message(response)
-      response.status_line
     end
 
     # Adds metadata to the request
     def add_metadata(request, metadata)
-      request.body = metadata.to_anvl unless metadata.nil? || metadata.empty?
+      return if metadata.nil? || metadata.empty?
+      metadata = Metadata.new(metadata) # copy/coerce
+      request.add_metadata(metadata) 
     end
 
     # Adds authentication to the request
     def add_authentication(request)
       if session.open?
-        request["Cookie"] = session.cookie 
+        request.add_authentication(cookie: session.cookie)
       else
-        request.basic_auth(user, password)
+        request.add_authentication(user: user, password: password)
       end
     end
 
+    # Does the login
     def do_login
-      request = Request.build(:login)
+      request = Request.new(:login)
       add_authentication(request)
       response = execute(request)
       session.open(response)
-      self
     end
 
+    # Does the logoug
     def do_logout
-      request = Request.build(:logout)
+      request = Request.new(:logout)
       execute(request)
       session.close
-      self
     end
 
   end

data/lib/ezid/configuration.rb

@@ -1,10 +1,24 @@
 require "logger"
 
 module Ezid
+  #
+  # EZID client configuration.
+  #
+  # Use Ezid::Client.configure to set values.
+  #
+  # @api private
   class Configuration
 
     attr_writer :user, :password, :logger
-    attr_accessor :metadata_profile, :default_status
+
+    # Default metadata profile (recommended)
+    attr_accessor :default_metadata_profile
+
+    # Default status - set only if default should not "public" (EZID default)
+    attr_accessor :default_status
+
+    # Default shoulder for minting (recommended)
+    attr_accessor :default_shoulder
 
     def user
       @user ||= ENV["EZID_USER"]
@@ -15,7 +29,7 @@ module Ezid
     end
 
     def logger
-      @logger ||= Logger.new(STDERR)
+      @logger ||= ::Logger.new(STDERR)
     end
 
   end

data/lib/ezid/identifier.rb

@@ -1,55 +1,128 @@
+require "forwardable"
+
 require_relative "metadata"
 
 module Ezid
+  #
+  # An EZID identifier resource.
+  #
+  # Identifier objects are instantiated by the class methods `create', `mint' and `find'.
+  #
+  # @api public 
   class Identifier
+    extend Forwardable
+
+    attr_reader :id
+
+    def_delegators :metadata, :status
+
+    private_class_method :new
 
     class << self
+      # Creates and EZID identifier
       def create(id, metadata=nil)
         response = Client.create_identifier(id, metadata)
-        Identifier.new(response.identifier)
+        new(response.identifier)
       end
 
-      def mint(metadata=nil)
+      # Mints an EZID identifier
+      def mint(shoulder=nil, metadata=nil)
         response = Client.mint_identifier(metadata)
-        identifier = Identifier.new(response.identifier)
+        identifier = new(response.identifier)
       end
 
+      # Find an EZID indentifier
       def find(id)
         response = Client.get_identifier_metadata(id)
-        Identifier.new(response.identifier, response.metadata)
+        new(response.identifier, response.metadata)
       end
     end
 
-    attr_reader :id
-
     def initialize(id, metadata=nil)
       @id = id
       @metadata = Metadata.new(metadata)
     end
 
+    # The identifier metadata, cached locally
+    # @return [Ezid::Metadata] the metadata
     def metadata
       reload if @metadata.empty?
       @metadata
     end
 
+    # The identifier which this identifier is shadowed by, or nil.
+    # @return [Ezid::Identifier] the shadowing identifier
+    def shadowed_by
+      Identifer.new(metadata.shadowedby) if metadata.shadowedby
+    end
+
+    # The identifer which this identifier shadows, or nil.
+    # @return [Ezid::Identifier] the shadowed identifier
+    def shadows
+      Identifier.new(metadata.shadows) if metadata.shadows
+    end
+
+    # Retrieve the current metadata for the identifier from EZID
+    # @return [Ezid::Identifier] the identifier
     def reload
       response = client.get_identifier_metadata(id)
-      @metadata.update(response.metadata)
+      @metadata = response.metadata
       self
     end
 
-    def client
-      @client ||= Client.new
+    # Clears the metadata on the identifier object
+    # @return [Ezid::Identifier] the identifier
+    def reset
+      @metadata = Metadata.new
+      self
     end
 
-    def save
-      response = client.modify_identifier(id, metadata)
-      response.success?
+    # Returns an EZID client
+    # @return [Ezid::Client] the client
+    def client
+      @client ||= Client.new
     end
 
+    # Deletes the identifier - caution!
     def delete
       response = client.delete_identifier(id)
-      response.success?
+      reset
+      freeze
+      response.message
+    end
+
+    # Sends the metadata to EZID - caution!
+    def update(metadata)
+      response = client.modify_identifier_metadata(metadata)
+      reset
+      response.message
+    end
+
+    def make_public!
+      update(_status: Metadata::PUBLIC)
+    end
+
+    def make_unavailable!
+      update(_status: Metadata::UNAVAILABLE)
+    end
+
+    def public?
+      status == Metadata::PUBLIC
+    end
+
+    def reserved?
+      status == Metadata::RESERVED
+    end
+
+    def unavailable?
+      status == Metadata::UNAVAILABLE
+    end
+
+    private
+
+    def remove(*elements)
+      metadata = elements.map { |el| [el, ""] }.to_h
+      update(metadata)
     end
 
   end

data/lib/ezid/logger.rb

@@ -0,0 +1,31 @@
+require "delegate"
+require "logger"
+
+module Ezid
+  #
+  # Custom logger for EZID client 
+  #
+  # @api private
+  class Logger < SimpleDelegator
+
+    # Logs a message for an EZID request/response
+    # @param request [Ezid::Request] the request
+    # @param response [Ezid::Response] the response
+    def request_and_response(request, response)
+      level = response.error? ? ::Logger::ERROR : ::Logger::INFO
+      response_message = response.status_line
+      message = "EZID #{request_message(request)}: #{response_message}"
+      log(level, message)
+    end
+
+    private
+
+    def request_message(request)
+      message = request.operation[0].to_s
+      args = request.operation[1..-1]
+      message << "(#{args.join(', ')})" if args.any?
+      message
+    end
+
+  end
+end

data/lib/ezid/metadata.rb

@@ -1,79 +1,151 @@
 require "forwardable"
 
 module Ezid
+  #
+  # EZID metadata collection for an identifier
+  #
+  # @api public
   class Metadata
     extend Forwardable
+    include Enumerable
 
+    # The metadata elements hash
     attr_reader :elements
-    def_delegators :elements, :[], :[]=, :empty?, :to_h, :to_a
 
-    ERC_PROFILE = "erc"
-    DC_PROFILE = "dc"
-    DATACITE_PROFILE = "datacite"
-    CROSSREF_PROFILE = "crossref"
+    def_delegators :elements, :each, :empty?, :[], :[]=
 
-    STATUS_PUBLIC = "public"
-    STATUS_RESERVED = "reserved"
-    STATUS_UNAVAILABLE = "unavailable"
+    # EZID metadata profiles
+    PROFILES = %w( erc dc datacite crossref )
 
-    # Internal metadata elements
+    # Public status
+    PUBLIC = "public"
+
+    # Reserved status
+    RESERVED = "reserved"
+
+    # Unavailable status
+    UNAVAILABLE = "unavailable"
+    
+    # EZID identifier status values
+    STATUS_VALUES = [PUBLIC, RESERVED, UNAVAILABLE].freeze
+
+    # EZID internal read-only metadata elements
     INTERNAL_READONLY_ELEMENTS = %w( _owner _ownergroup _created _updated _shadows _shadowedby _datacenter ).freeze
+
+    # EZID internal writable metadata elements
     INTERNAL_READWRITE_ELEMENTS = %w( _coowners _target _profile _status _export _crossref ).freeze        
+
+    # EZID internal metadata elements
     INTERNAL_ELEMENTS = (INTERNAL_READONLY_ELEMENTS + INTERNAL_READWRITE_ELEMENTS).freeze
+
+    # Internal metadata element which are datetime values
+    # @note EZID outputs datetime info as epoch seconds.
+    DATETIME_ELEMENTS = %w( _created _updated ).freeze
     
-    ANVL_SEPARATOR = ": ".freeze
+    # EZID metadata field/value separator
+    ANVL_SEPARATOR = ": "
 
-    # Creates a reader method for each internal metadata element
-    INTERNAL_ELEMENTS.each do |element|
-      reader = element.sub("_", "").to_sym
-      define_method(reader) do
-        self[element]
-      end
-    end
+    # Characters to escape on output to EZID
+    ESCAPE_RE = /[%:\r\n]/
 
-    # Creates a writer method for each writable internal metadata element
-    INTERNAL_READWRITE_ELEMENTS.each do |element|
-      writer = "#{element.sub('_', '')}=".to_sym
-      define_method(writer) do |value|
-        self[element] = value
-      end
-    end
+    # Character sequence to unescape from EZID
+    UNESCAPE_RE = /%\h\h/
+
+    # A comment line
+    COMMENT_RE = /^#.*(\r?\n)?/ 
+
+    # A line continuation
+    LINE_CONTINUATION_RE = /\r?\n\s+/
+
+    # A line ending
+    LINE_ENDING_RE = /\r?\n/
 
-    # @param data [Hash, String, Ezid::Metadata] EZID metadata
     def initialize(data={})
       @elements = coerce(data)
     end
 
-    # @todo escape \n, \r and %
-    # @todo force UTF-8
+    # Output metadata in EZID ANVL format
     # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
+    # @return [String] the ANVL output
     def to_anvl
-      to_a.map { |pair| pair.join(ANVL_SEPARATOR) }.join("\n")
+      lines = map { |element| element.map { |e| escape(e) }.join(ANVL_SEPARATOR) }
+      lines.join("\n").force_encoding(Encoding::UTF_8)
     end
 
     def to_s
       to_anvl
     end
 
-    # Add metadata
+    # Adds metadata to the collection
+    # @param data [String, Hash, Ezid::Metadata] the data to add
+    # @return [Ezid::Metadata] the updated metadata
     def update(data)
       elements.update(coerce(data))
+      self
+    end
+
+    # method_missing is used to provide internal element readers and writers
+    def method_missing(name, *args)
+      if INTERNAL_ELEMENTS.include?(element = "_#{name}")
+        reader(element) 
+      elsif name.to_s.end_with?("=") && INTERNAL_READWRITE_ELEMENTS.include?(element = "_#{name}".sub("=", ""))
+        writer(element, args.first) 
+      else
+        super
+      end
     end
 
     private
 
+    def reader(element)
+      value = self[element]
+      return Time.at(value.to_i) if DATETIME_ELEMENTS.include?(element) && !value.nil?
+      value
+    end
+
+    def writer(element, value)
+      self[element] = value
+    end
+
     # Coerce data into a Hash of elements
-    # @todo unescape 
-    # @see {#to_anvl}
     def coerce(data)
       begin
-        data.to_h
+        stringify_keys(data.to_h)
       rescue NoMethodError
-        # This does not account for comments and continuation lines
-        # http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
-        data.split(/\r?\n/).map { |line| line.split(ANVL_SEPARATOR, 2) }.to_h
+        coerce_string(data)
       end
     end
 
+    def stringify_keys(hsh)
+      hsh.keys.map(&:to_s).zip(hsh.values).to_h
+    end
+
+    # Escape value for sending to EZID host
+    # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
+    # @param value [String] the value to escape
+    # @return [String] the escaped value
+    def escape(value)
+      value.gsub(ESCAPE_RE) { |m| URI.encode(m) }
+    end
+
+    # Unescape value from EZID host (or other source)
+    # @see http://ezid.cdlib.org/doc/apidoc.html#request-response-bodies
+    # @param value [String] the value to unescape
+    # @return [String] the unescaped value
+    def unescape(value)
+      value.gsub(UNESCAPE_RE) { |m| URI.decode(m) }
+    end
+    
+    # Coerce a string of metadata (e.g., from EZID host) into a Hash
+    # @param data [String] the string to coerce
+    # @return [Hash] the hash of coerced data
+    def coerce_string(data)
+      data.gsub(COMMENT_RE, "")
+        .gsub(LINE_CONTINUATION_RE, " ")
+        .split(LINE_ENDING_RE)
+        .map { |line| line.split(ANVL_SEPARATOR, 2).map { |v| unescape(v).strip } }
+        .to_h
+    end
+
   end
 end

data/lib/ezid/request.rb

@@ -1,33 +1,54 @@
 require "uri"
 require "net/http"
-require "delegate"
-
-require_relative "api"
-require_relative "response"
 
 module Ezid
   #
   # A request to the EZID service.
   #
-  class Request < SimpleDelegator
+  # @note A Request should only be created by an Ezid::Client instance.
+  # @api private
+  class Request
 
     EZID_HOST = "ezid.cdlib.org"
     CHARSET = "UTF-8"
     CONTENT_TYPE = "text/plain"
 
-    def self.build(op, *args)
-      http_method, path, query = Api.send(op, *args)
-      uri = URI::HTTPS.build(host: EZID_HOST, path: path, query: query)
-      http_request = Net::HTTP.const_get(http_method).new(uri)
-      Request.new(http_request)
+    attr_reader :http_request, :uri, :operation
+
+    def initialize(*args)
+      @operation = args
+      http_method, path, query = Api.send(*args)
+      @uri = URI::HTTPS.build(host: EZID_HOST, path: path, query: query)
+      @http_request = Net::HTTP.const_get(http_method).new(uri)
+      @http_request.set_content_type(CONTENT_TYPE, charset: CHARSET)
     end
 
+    # Executes the request and returns the HTTP response
+    # @return [Net::HTTPResponse] the response
     def execute
-      http_response = Net::HTTP.start(uri.host, use_ssl: true) do |http|
-        set_content_type(CONTENT_TYPE, charset: CHARSET)
-        http.request(__getobj__)
+      Net::HTTP.start(uri.host, use_ssl: true) do |http|
+        http.request(http_request)
       end
-      Response.build(http_response)
+    end
+
+    # Adds authentication data to the request
+    # @param opts [Hash] the options.
+    #   Must include either: `:cookie`, or: `:user` and `:password`.
+    # @option opts [String] :cookie a session cookie
+    # @option opts [String] :user user name for basic auth
+    # @option opts [String] :password password for basic auth
+    def add_authentication(opts={})
+      if opts[:cookie]
+        http_request["Cookie"] = opts[:cookie]
+      else
+        http_request.basic_auth(opts[:user], opts[:password])
+      end
+    end
+
+    # Adds EZID metadata (if any) to the request body
+    # @param metadata [Ezid::Metadata] the metadata to add
+    def add_metadata(metadata)
+      http_request.body = metadata.to_anvl unless metadata.empty?
     end
 
   end

data/lib/ezid/response.rb

@@ -1,38 +1,55 @@
 require "delegate"
 
 module Ezid
+  #
   # A response from the EZID service.
+  #
+  # @note A Response should only be created by an Ezid::Client instance.
+  # @api private
   class Response < SimpleDelegator
 
+    # Success response status
     SUCCESS = "success"
-    ERROR = "error"
 
-    def self.build(http_response)
-      Response.new(http_response)
-    end
+    # Error response status
+    ERROR = "error"
 
+    # The response status -- "success" or "error"
+    # @return [String] the status
     def status
       @status ||= status_line.split(/: /)
     end
 
+    # The status line of the response
+    # @return [String] the status line
     def status_line
       content.first
     end
 
+    # The body of the response split into: status line and rest of body
+    # @return [Array] status line, rest of body
     def content
       @content ||= body.split(/\r?\n/, 2)
     end
 
+    # Metadata (if any) parsed out of the response
+    # @return [Ezid::Metadata] the metadata
     def metadata
-      content.last if success? && identifier_uri?
+      return @metadata if @metadata
+      if success? && identifier_uri?
+        @metadata = Metadata.new(content.last) 
+      end
+      @metadata
     end
 
+    # The identifier string parsed out of the response
+    # @return [String] the identifier
     def identifier
       message.split(/\s/).first if success? && identifier_uri?
     end
 
     def identifier_uri?
-      uri.path =~ /^\/(id|shoulder)\//
+      ( uri.path =~ /^\/(id|shoulder)\// ) && true
     end
 
     def outcome

data/lib/ezid/session.rb

@@ -4,6 +4,10 @@ require "net/http"
 require_relative "request"
 
 module Ezid
+  #
+  # An EZID session
+  #
+  # @api private
   class Session
 
     attr_reader :cookie

data/lib/ezid/test_helper.rb

@@ -1,9 +1,14 @@
 module Ezid
   module TestHelper
-    
-    TEST_USER = "apitest"
+
     ARK_SHOULDER = "ark:/99999/fk4"
     DOI_SHOULDER = "doi:10.5072/FK2"
+    USER = "apitest"
+
+    Client.configure do |config|
+      config.user = USER
+      config.default_shoulder = ARK_SHOULDER
+    end
 
     def doi_metadata
       Metadata.new("datacite.title" => "Test", 

data/spec/lib/ezid/client_spec.rb

@@ -2,22 +2,19 @@ module Ezid
   RSpec.describe Client do
     describe "initialization" do
       describe "without a block" do
-        subject { described_class.new(user: TEST_USER) }
         it "should not be logged in" do
           expect(subject).not_to be_logged_in
         end
       end
       describe "with a block", :vcr do
         it "should be logged in" do
-          described_class.new(user: TEST_USER) do |client|
+          described_class.new do |client|
             expect(client).to be_logged_in
           end
         end
       end
-    end
-    
+    end    
     describe "authentication", :vcr do
-      subject { described_class.new(user: TEST_USER) }
       describe "logging in" do
         before { subject.login }
         it "should be logged in" do
@@ -25,54 +22,67 @@ module Ezid
         end
       end
       describe "logging out" do
-        before { subject.login; subject.logout }
+        before { subject.login }
         it "should not be logged in" do
+          subject.logout
           expect(subject).not_to be_logged_in
         end
       end
     end
-    describe "creating an identifier" do
+    describe "creating an identifier", :vcr do
       # TODO
     end
     describe "minting an identifier", :vcr do
-      let(:client) { described_class.new(user: TEST_USER) }
       describe "which is an ARK" do
-        subject { client.mint_identifier(ARK_SHOULDER) }
         it "should be a success" do
-          expect(subject).to be_success
-          expect(subject.message).to match(/#{ARK_SHOULDER}/)
+          response = subject.mint_identifier(ARK_SHOULDER)
+          expect(response).to be_success
+          expect(response.message).to match(/#{ARK_SHOULDER}/)
         end
       end
       describe "which is a DOI" do
-        subject { client.mint_identifier(DOI_SHOULDER, doi_metadata) }
         it "should be a sucess" do
-          expect(subject).to be_success
-          expect(subject.message).to match(/#{DOI_SHOULDER}/)
-          expect(subject.message).to match(/\| ark:/)
+          response = subject.mint_identifier(DOI_SHOULDER, doi_metadata)
+          expect(response).to be_success
+          expect(response.message).to match(/#{DOI_SHOULDER}/)
+          expect(response.message).to match(/\| ark:/)
         end
       end
     end
-    describe "getting identifier metadata", :vcr do
-      let(:client) { described_class.new(user: TEST_USER) }
-      let(:metadata) { Metadata.new("dc.title" => "Test") }
-      let(:identifier) { client.mint_identifier(ARK_SHOULDER, metadata).message }
-      subject { Metadata.new(client.get_identifier_metadata(identifier).content.last) }
+    describe "getting identifier metadata" do
+      before do
+        @identifier = subject.mint_identifier(ARK_SHOULDER).identifier
+      end
       it "should return the metadata" do
-        expect(subject["dc.title"]).to eq("Test")
+        response = subject.get_identifier_metadata(@identifier)
+        expect(response.body).to match(/_status: public/)
       end
     end
     describe "modifying an identifier" do
-      # TODO
+      before do
+        @identifier = subject.mint_identifier(ARK_SHOULDER).identifier
+      end
+      it "should update the metadata" do
+        subject.modify_identifier(@identifier, "dc.title" => "Test")
+        response = subject.get_identifier_metadata(@identifier)
+        expect(response.body).to match(/dc.title: Test/)
+      end
     end
     describe "deleting an identifier" do
-      # TODO
+      before do
+        @identifier = subject.mint_identifier(ARK_SHOULDER, "_status" => "reserved").identifier 
+      end
+      it "should delete the identifier" do
+        response = subject.delete_identifier(@identifier) 
+        expect(response).to be_success
+        expect { subject.get_identifier_metadata(@identifier) }.to raise_error
+      end
     end
     describe "server status", :vcr do
-      let(:client) { described_class.new(user: TEST_USER) }
-      subject { client.server_status("*") }
       it "should report the status of EZID and subsystems" do
-        expect(subject).to be_success
-        expect(subject.message).to eq "EZID is up"        
+        response =  subject.server_status("*")
+        expect(response).to be_success
+        expect(response.message).to eq("EZID is up")
       end
     end
   end

data/spec/lib/ezid/identifier_spec.rb

@@ -0,0 +1,5 @@
+module Ezid
+  RSpec.describe Identifier do
+
+  end
+end

data/spec/lib/ezid/metadata_spec.rb

@@ -0,0 +1,62 @@
+module Ezid
+  RSpec.describe Metadata do
+    describe "method missing" do
+      context "for an internal metadata element name w/o leading underscore" do
+        it "should call the reader method" do
+          expect(subject).to receive(:reader).with("_status")
+          subject.status
+        end
+      end
+      context "for an internal writable metadata element name + '=' and w/o leading underscore" do
+        it "should call the writer method" do
+          expect(subject).to receive(:writer).with("_status", "public")
+          subject.status = "public"
+        end
+      end
+    end
+    describe "internal element reader" do
+      context "for a datetime element" do
+        before { subject["_created"] = "1416507086" }
+        it "should return a Time" do          
+          expect(subject.created).to be_a(Time)
+        end
+      end
+      context "for a non-datetime element" do
+        before { subject["_status"] = "public" }
+        it "should return the value" do
+          expect(subject.status).to eq("public")
+        end
+      end
+    end
+    describe "internal element writer" do
+      before { subject["_status"] = "reserved" }
+      it "should set the element" do
+        expect { subject.status = "public" }.to change { subject["_status"] }.from("reserved").to("public")
+      end
+    end
+    describe "ANVL output" do
+      let(:metadata) { described_class.new(_updated: "1416507086",
+                                           _target: "http://ezid.cdlib.org/id/ark:/99999/fk4fn19h87",
+                                           _profile: "erc",
+                                           _ownergroup: "apitest",
+                                           _owner: "apitest",
+                                           _export: "yes",
+                                           _created: "1416507086",
+                                           _status: "public") }
+      it "should output the proper format" do
+        expect(metadata.to_anvl).to eq("\
+_updated: 1416507086
+_target: http://ezid.cdlib.org/id/ark:/99999/fk4fn19h87
+_profile: erc
+_ownergroup: apitest
+_owner: apitest
+_export: yes
+_created: 1416507086
+_status: public")
+      end
+    end
+    describe "coercion" do
+
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ezid-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - dchandekstark
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-20 00:00:00.000000000 Z
+date: 2014-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -101,12 +101,15 @@ files:
 - lib/ezid/configuration.rb
 - lib/ezid/error.rb
 - lib/ezid/identifier.rb
+- lib/ezid/logger.rb
 - lib/ezid/metadata.rb
 - lib/ezid/request.rb
 - lib/ezid/response.rb
 - lib/ezid/session.rb
 - lib/ezid/test_helper.rb
 - spec/lib/ezid/client_spec.rb
+- spec/lib/ezid/identifier_spec.rb
+- spec/lib/ezid/metadata_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/duke-libraries/ezid-client
 licenses:
@@ -134,4 +137,6 @@ specification_version: 4
 summary: Ruby client for EZID API Version 2
 test_files:
 - spec/lib/ezid/client_spec.rb
+- spec/lib/ezid/identifier_spec.rb
+- spec/lib/ezid/metadata_spec.rb
 - spec/spec_helper.rb