Raised by Gem::Validator when something is not right in a gem.
Raised to indicate that a system exit should occur with the specified exit_code
Raised by Resolver when a dependency requests a gem for which there is no spec.
Example using a Gem::Package
Builds a .gem file given a Gem::Specification. A .gem file is a tarball which contains a data.tar.gz, metadata.gz, checksums.yaml.gz and possibly signatures.
require 'rubygems' require 'rubygems/package' spec = Gem::Specification.new do |s| s.summary = "Ruby based make-like utility." s.name = 'rake' s.version = PKG_VERSION s.requirements << 'none' s.files = PKG_FILES s.description = <<-EOF Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax. EOF end Gem::Package.build spec
Reads a .gem file.
require 'rubygems' require 'rubygems/package' the_gem = Gem::Package.new(path_to_dot_gem) the_gem.contents # get the files in the gem the_gem.extract_files destination_directory # extract the gem into a directory the_gem.spec # get the spec out of the gem the_gem.verify # check the gem is OK (contains valid gem specification, contains a not corrupt contents archive)
files are the files in the .gem tar file, not the Ruby files in the gem extract_files and contents automatically call verify
Create a package based upon a Gem::Specification. Gem packages, as well as zip files and tar/gzipped packages can be produced by this task.
In addition to the Rake targets generated by Rake::PackageTask, a Gem::PackageTask will also generate the following tasks:
Create a RubyGems package with the given name and version.
Example using a Gem::Specification:
require 'rubygems' require 'rubygems/package_task' spec = Gem::Specification.new do |s| s.summary = "Ruby based make-like utility." s.name = 'rake' s.version = PKG_VERSION s.requirements << 'none' s.files = PKG_FILES s.description = <<-EOF Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax. EOF end Gem::PackageTask.new(spec) do |pkg| pkg.need_zip = true pkg.need_tar = true end
A Requirement is a set of one or more version restrictions. It supports a few (=, !=, >, <, >=, <=, ~>) different restriction operators.
See Gem::Version for a description on how versions and requirements work together in RubyGems.
The Specification class contains the information for a gem. Typically defined in a .gemspec file or a Rakefile, and looks like this:
Gem::Specification.new do |s| s.name = 'example' s.version = '0.1.0' s.licenses = ['MIT'] s.summary = "This is an example!" s.description = "Much longer explanation of the example!" s.authors = ["Ruby Coder"] s.email = 'rubycoder@example.com' s.files = ["lib/example.rb"] s.homepage = 'https://rubygems.org/gems/example' s.metadata = { "source_code_uri" => "https://github.com/example/example" } end
Starting in RubyGems 2.0, a Specification can hold arbitrary metadata. See metadata for restrictions on the format and size of metadata items you may add to a specification.
Gem::StubSpecification reads the stub: line from the gemspec. This prevents us having to eval the entire gemspec in order to find out certain information.
The UriFormatter handles URIs from user-input and escaping.
uf = Gem::UriFormatter.new 'example.com' p uf.normalize #=> 'http://example.com'
Gem::StreamUI implements a simple stream based user interface.
Validator performs various gem file and gem database validation
This class is responsible for taking a code block that exists at a far indentaion and then iteratively increasing the block so that it captures everything within the same indentation block.
def dog puts "bow" puts "wow" end
block = BlockExpand.new(code_lines: code_lines)
.call(CodeBlock.new(lines: code_lines[1]))
puts block.to_s # => puts “bow”
puts "wow"
Once a code block has captured everything at a given indentation level then it will expand to capture surrounding indentation.
block = BlockExpand.new(code_lines: code_lines)
.call(block)
block.to_s # => def dog
puts "bow" puts "wow" end
Parses and sanitizes source into a lexically aware document
Internally the document is represented by an array with each index containing a CodeLine correlating to a line from the source code.
There are three main phases in the algorithm:
Sanitize/format input source
Search for invalid blocks
Format invalid blocks into something meaninful
This class handles the first part.
The reason this class exists is to format input source for better/easier/cleaner exploration.
The CodeSearch class operates at the line level so we must be careful to not introduce lines that look valid by themselves, but when removed will trigger syntax errors or strange behavior.
## Join Trailing slashes
Code with a trailing slash is logically treated as a single line:
1 it "code can be split" \ 2 "across multiple lines" do
In this case removing line 2 would add a syntax error. We get around this by internally joining the two lines into a single “line” object
## Logically Consecutive lines
Code that can be broken over multiple lines such as method calls are on different lines:
1 User. 2 where(name: "schneems"). 3 first
Removing line 2 can introduce a syntax error. To fix this, all lines are joined into one.
## Heredocs
A heredoc is an way of defining a multi-line string. They can cause many problems. If left as a single line, the parser would try to parse the contents as ruby code rather than as a string. Even without this problem, we still hit an issue with indentation:
1 foo = <<~HEREDOC 2 "Be yourself; everyone else is already taken."" 3 ― Oscar Wilde 4 puts "I look like ruby code" # but i'm still a heredoc 5 HEREDOC
If we didn’t join these lines then our algorithm would think that line 4 is separate from the rest, has a higher indentation, then look at it first and remove it.
If the code evaluates line 5 by itself it will think line 5 is a constant, remove it, and introduce a syntax errror.
All of these problems are fixed by joining the whole heredoc into a single line.
## Comments and whitespace
Comments can throw off the way the lexer tells us that the line logically belongs with the next line. This is valid ruby but results in a different lex output than before:
1 User. 2 where(name: "schneems"). 3 # Comment here 4 first
To handle this we can replace comment lines with empty lines and then re-lex the source. This removal and re-lexing preserves line index and document size, but generates an easier to work with document.
Outputs code with highlighted lines
Whatever is passed to this class will be rendered even if it is “marked invisible” any filtering of output should be done before calling this class.
DisplayCodeWithLineNumbers.new(
lines: lines,
highlight_lines: [lines[2], lines[3]]
).call
# =>
1
2 def cat
> 3 Dir.chdir
> 4 end
5 end
6
This class is responsible for generating initial code blocks that will then later be expanded.
The biggest concern when guessing code blocks, is accidentally grabbing one that contains only an “end”. In this example:
def dog begonn # misspelled `begin` puts "bark" end end
The following lines would be matched (from bottom to top):
1) end 2) puts "bark" end 3) begonn puts "bark" end
At this point it has no where else to expand, and it will yield this inner code as a block
Class that parses String’s into URI’s.
It contains a Hash set of patterns and Regexp’s that match and validate.
A Process::Status contains information about a system process.
Thread-local variable $? is initially nil. Some methods assign to it a Process::Status object that represents a system process (either running or terminated):
`ruby -e "exit 99"` stat = $? # => #<Process::Status: pid 1262862 exit 99> stat.class # => Process::Status stat.to_i # => 25344 stat.stopped? # => false stat.exited? # => true stat.exitstatus # => 99
A mixin that provides methods for parsing C struct and prototype signatures.
require 'fiddle/import' include Fiddle::CParser #=> Object parse_ctype('int') #=> Fiddle::TYPE_INT parse_struct_signature(['int i', 'char c']) #=> [[Fiddle::TYPE_INT, Fiddle::TYPE_CHAR], ["i", "c"]] parse_signature('double sum(double, double)') #=> ["sum", Fiddle::TYPE_DOUBLE, [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_DOUBLE]]