Module: Stickler::Repository::Api

Defined in:
lib/stickler/repository/api.rb

Overview

The API that all Stickler Repository classes MUST implement. This file is here to document the API

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.api_methods ⇒ Object

:stopdoc:



145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/stickler/repository/api.rb', line 145

def self.api_methods
  %w[
      delete
      gems_uri
      get
      open
      push
      search_for
      uri
      uri_for_gem
      yank
    ]
end

Instance Method Details

#delete(spec) ⇒ Object

:call-seq:

repo.delete( spec ) -> true|false

Remove the gem matching the spec completely from the respository. Return true if the gem was removed, false otherwise

Raises:

  • (NotImplementedError) 


85
86
87
 
# File 'lib/stickler/repository/api.rb', line 85

def delete( spec )
  raise NotImplementedError, not_implemented_msg( :delete)
end

#gems_uri ⇒ Object

:call-seq:

repo.gems_uri -> URI

Return the URI to the location holding all the .gem files.

Raises:

  • (NotImplementedError) 


27
28
29
 
# File 'lib/stickler/repository/api.rb', line 27

def gems_uri
  raise NotImplementedError, not_implemented_msg( :gems_uri )
end

#get(spec) ⇒ Object

:call-seq:

repo.get( spec ) -> bytes

Retrieve the gem matching the spec from the repository. The bytes returned MUST be something that would be acceptable to be written directly to disk as a .gem file.

If the gem described by spec does not exist, nil is returned.

Raises:

  • (NotImplementedError) 


123
124
125
 
# File 'lib/stickler/repository/api.rb', line 123

def get( spec )
  raise NotImplementedError, not_implemented_msg( :get )
end

#open(spec, &block) ⇒ Object

:call-seq:

repo.open( spec ) -> reader
repo.open( spec ) { |reader| block }

Open the gem in a readonly manner, similar to that of File.open. the reader object that is returned MUST respond to read, close and rewind. These methods behave like their corresponding IO#read, IO#close and IO#rewind methods.

If the gem described by spec does not exist, nil is returned. If the gem described by spec does not exist, the block is not called.

Raises:

  • (NotImplementedError) 


140
141
142
 
# File 'lib/stickler/repository/api.rb', line 140

def open( spec, &block )
  raise NotImplementedError, not_implemented_msg( :open )
end

#push(path_to_gem_file) ⇒ Object

:call-seq:

repo.push( path_to_gem_file ) -> Stickler::SpecLite

Push, in the sense of the gem commandline command gem push. path_to_gem_file must be a file system location to a .gem file that is then pushed into the repository.

The SpecLite returned can be used to retrieve the gem from the repo using the #get() method. A direct URI to the gem may be obtained using the #uri_for() method.

If the gem pushed already exists, then a Stickler::Repository::Error is raised.

Raises:

  • (NotImplementedError) 


74
75
76
 
# File 'lib/stickler/repository/api.rb', line 74

def push( path_to_gem_file )
  raise NotImplementedError, not_implemented_msg( :push )
end

#search_for(spec) ⇒ Object

:call-seq:

repo.search_for( spec ) -> Array

match MUST be an object that responds to name, version and platform.

The Array that is returned will be empty? if no gems are found that match match.

When one or matches is found, the Array will contain contain Stickler::SpecLite instances.

Raises:

  • (NotImplementedError) 


55
56
57
 
# File 'lib/stickler/repository/api.rb', line 55

def search_for( spec )
  raise NotImplementedError, not_implemented_msg( :search_for )
end

#uri ⇒ Object

:call-seq:

repo.uri -> URI

Return the URI of the repo

Raises:

  • (NotImplementedError) 


16
17
18
 
# File 'lib/stickler/repository/api.rb', line 16

def uri
  raise NotImplementedError, not_implemented_msg( :uri )
end

#uri_for_gem(spec) ⇒ Object

:call-seq:

repo.uri_for_gem( spec ) -> URI

Given a SpecLite like object, return a URI that can be used to directly access the gem in the repository.

Raises:

  • (NotImplementedError) 


38
39
40
 
# File 'lib/stickler/repository/api.rb', line 38

def uri_for_gem( spec )
  raise NotImplementedError, not_implemented_msg( :uri_for_gem )
end

#yank(spec) ⇒ Object

:call-seq:

repo.yank( spec ) -> Stickler::SpecLite

“yank” in the sense of update.gemcutter.org/2010/03/05/february-changelog.html. This means, remove the gem matching spec from the index, so it will not be found when searching, but do not remove the gem physically from the server. It can still be downloaded directly.

The SpecLite instance that is returned will have the information that may be used in the #get() or #uri_for_gem() methods to retrieve the actual gemfile.

After a gem has been ‘yanked’ it MUST not longer be found via the #search_for() method, nor can it’s specification be retrieved via the #uri_for_specification() method.

If the gem described by spec does not exist, nil is returned.

Raises:

  • (NotImplementedError) 


109
110
111
 
# File 'lib/stickler/repository/api.rb', line 109

def yank( spec )
  raise NotImplementedError, not_implemented_msg( :yank )
end