require 'noumenon'

# The base class for content repositories. This class is predominantly present just to document the
# expected API for a repository.
#
# @api public
class Noumenon::ContentRepository
  autoload :FileSystem, 'noumenon/content_repository/file_system'
  
  # Provides access to options set on initialization.
  # @api public
  attr_reader :options
  
  # Create a new Repository instance.
  #
  # @param [ Hash, #each ] options A hash of options to use when configuring the repository.
  # @api public
  def initialize(options = {})
    @options = options
  end
  
  # Save an item in the repository. If an item already exists then it should be overwritten.
  #
  # @param [ #to_s ] path The path the save the content at.
  # @param [ Hash, #each ] content A hash of key/value pairs to use as the content.
  # @api public
  def put(path, content)
    not_supported "updating it's contents"
  end
  
  # Load an item from the repository. If the item does not exist then `nil` should be returned.
  #
  # @param [ #to_s ] path The path to laod content from
  # @return [ Hash, #each, nil ] Either the hash stored at the specified path, or nil if no content was found.
  # @api public
  def get(path)
    not_supported "reading it's contents"
  end
  
  # Returns an array of content items below the root specified. If depth is greater then 1 that
  # many sub-directories will also be checked, with any items in those being placed in a `:children` attribute
  # on the parent.
  #
  # @param [ #to_s ] root The path to start searching from.
  # @param [ Integer ] depth The number of sub-directories to check.
  # @return [ Array, #each ] An array of child items.
  # @api public
  #
  # @example
  #   Noumenon.content_repository.children("/", 2)
  #   # => [ 
  #   #      { 
  #   #        path: "/about", title: "About, children: [
  #   #          { path: "/about/team", title: "The Team" },
  #   #          { path: "/about/area", title: "The Area" }
  #   #        ]
  #   #      }
  #   #    ]
  #
  def children(root = "/", depth = 1)
    not_supported "listing children from a path"
  end

  protected
  def not_supported(action)
    raise NotImplementedError.new("This repository type does not support #{action}.")
  end
end