MatchData
is the type of the special variable $~
, and is the type of the object returned by Regexp#match
and Regexp.last_match
. It encapsulates all the results of a pattern match, results normally accessed through the special variables $&
, $'
, $`
, $1
, $2
, and so on.
RDoc::Task
creates the following rake tasks to generate and clean up RDoc
output:
Main task for this RDoc
task.
Delete all the rdoc files. This target is automatically added to the main clobber target.
Rebuild the rdoc files from scratch, even if they are not out of date.
Simple Example:
require 'rdoc/task' RDoc::Task.new do |rdoc| rdoc.main = "README.rdoc" rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb") end
The rdoc
object passed to the block is an RDoc::Task
object. See the attributes list for the RDoc::Task
class for available customization options.
You may wish to give the task a different name, such as if you are generating two sets of documentation. For instance, if you want to have a development set of documentation including private methods:
require 'rdoc/task' RDoc::Task.new :rdoc_dev do |rdoc| rdoc.main = "README.doc" rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb") rdoc.options << "--all" end
The tasks would then be named :rdoc_dev, :clobber_rdoc_dev, and :rerdoc_dev.
If you wish to have completely different task names, then pass a Hash
as first argument. With the :rdoc
, :clobber_rdoc
and :rerdoc
options, you can customize the task names to your liking.
For example:
require 'rdoc/task' RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean", :rerdoc => "rdoc:force")
This will create the tasks :rdoc
, :rdoc:clean
and :rdoc:force
.
Shell
implements an idiomatic Ruby interface for common UNIX shell commands.
It provides users the ability to execute commands with filters and pipes, like sh
/csh
by using native facilities of Ruby.
In this example we will create three tmpFile
‘s in three different folders under the /tmp
directory.
sh = Shell.cd("/tmp") # Change to the /tmp directory sh.mkdir "shell-test-1" unless sh.exists?("shell-test-1") # make the 'shell-test-1' directory if it doesn't already exist sh.cd("shell-test-1") # Change to the /tmp/shell-test-1 directory for dir in ["dir1", "dir3", "dir5"] if !sh.exists?(dir) sh.mkdir dir # make dir if it doesn't already exist sh.cd(dir) do # change to the `dir` directory f = sh.open("tmpFile", "w") # open a new file in write mode f.print "TEST\n" # write to the file f.close # close the file handler end print sh.pwd # output the process working directory end end
This example is identical to the first, except we’re using CommandProcessor#transact
.
CommandProcessor#transact
executes the given block against self, in this case sh
; our Shell
object. Within the block we can substitute sh.cd
to cd
, because the scope within the block uses sh
already.
sh = Shell.cd("/tmp") sh.transact do mkdir "shell-test-1" unless exists?("shell-test-1") cd("shell-test-1") for dir in ["dir1", "dir3", "dir5"] if !exists?(dir) mkdir dir cd(dir) do f = open("tmpFile", "w") f.print "TEST\n" f.close end print pwd end end end
In this example we will read the operating system file /etc/printcap
, generated by cupsd
, and then output it to a new file relative to the pwd
of sh
.
sh = Shell.new sh.cat("/etc/printcap") | sh.tee("tee1") > "tee2" (sh.cat < "/etc/printcap") | sh.tee("tee11") > "tee12" sh.cat("/etc/printcap") | sh.tee("tee1") >> "tee2" (sh.cat < "/etc/printcap") | sh.tee("tee11") >> "tee12"
This is a recommended base class for C extensions using Data_Make_Struct or Data_Wrap_Struct, see doc/extension.rdoc for details.
The global value false
is the only instance of class FalseClass
and represents a logically false value in boolean expressions. The class provides operators allowing false
to participate correctly in logical expressions.
Raised when Ruby can’t yield as requested.
A typical scenario is attempting to yield when no block is given:
def call_block yield 42 end call_block
raises the exception:
LocalJumpError: no block given (yield)
A more subtle example:
def get_me_a_return Proc.new { return 42 } end get_me_a_return.call
raises the exception:
LocalJumpError: unexpected return
Raised in case of a stack overflow.
def me_myself_and_i me_myself_and_i end me_myself_and_i
raises the exception:
SystemStackError: stack level too deep
This module manipulates strings according to the word parsing rules of the UNIX Bourne shell.
The shellwords() function was originally a port of shellwords.pl, but modified to conform to the Shell
& Utilities volume of the IEEE Std 1003.1-2008, 2016 Edition [1].
You can use Shellwords
to parse a string into a Bourne shell friendly Array.
require 'shellwords' argv = Shellwords.split('three blind "mice"') argv #=> ["three", "blind", "mice"]
Once you’ve required Shellwords
, you can use the split alias String#shellsplit
.
argv = "see how they run".shellsplit argv #=> ["see", "how", "they", "run"]
Be careful you don’t leave a quote unmatched.
argv = "they all ran after the farmer's wife".shellsplit #=> ArgumentError: Unmatched double quote: ...
In this case, you might want to use Shellwords.escape
, or its alias String#shellescape
.
This method will escape the String for you to safely use with a Bourne shell.
argv = Shellwords.escape("special's.txt") argv #=> "special\\'s.txt" system("cat " + argv)
Shellwords
also comes with a core extension for Array, Array#shelljoin
.
argv = %w{ls -lta lib} system(argv.shelljoin)
You can use this method to create an escaped string out of an array of tokens separated by a space. In this example we used the literal shortcut for Array.new
.
Wakou Aoyama
Akinori MUSHA <knu@iDaemons.org>
Akinori MUSHA <knu@iDaemons.org> (current maintainer)
1: IEEE Std 1003.1-2008, 2016 Edition, the Shell & Utilities volume
automatically generated by template/unicode_norm_gen.tmpl
The marshaling library converts collections of Ruby objects into a byte stream, allowing them to be stored outside the currently active script. This data may subsequently be read and the original objects reconstituted.
Marshaled data has major and minor version numbers stored along with the object information. In normal use, marshaling can only load data written with the same major version number and an equal or lower minor version number. If Ruby’s “verbose” flag is set (normally using -d, -v, -w, or –verbose) the major and minor numbers must match exactly. Marshal
versioning is independent of Ruby’s version numbers. You can extract the version by reading the first two bytes of marshaled data.
str = Marshal.dump("thing") RUBY_VERSION #=> "1.9.0" str[0].ord #=> 4 str[1].ord #=> 8
Some objects cannot be dumped: if the objects to be dumped include bindings, procedure or method objects, instances of class IO
, or singleton objects, a TypeError
will be raised.
If your class has special serialization needs (for example, if you want to serialize in some specific format), or if it contains objects that would otherwise not be serializable, you can implement your own serialization strategy.
There are two methods of doing this, your object can define either marshal_dump and marshal_load or _dump and _load. marshal_dump will take precedence over _dump if both are defined. marshal_dump may result in smaller Marshal
strings.
By design, Marshal.load
can deserialize almost any class loaded into the Ruby process. In many cases this can lead to remote code execution if the Marshal
data is loaded from an untrusted source.
As a result, Marshal.load
is not suitable as a general purpose serialization format and you should never unmarshal user supplied input or other untrusted data.
If you need to deserialize untrusted data, use JSON
or another serialization format that is only able to load simple, ‘primitive’ types such as String, Array, Hash
, etc. Never allow user input to specify arbitrary types to deserialize into.
When dumping an object the method marshal_dump will be called. marshal_dump must return a result containing the information necessary for marshal_load to reconstitute the object. The result can be any object.
When loading an object dumped using marshal_dump the object is first allocated then marshal_load is called with the result from marshal_dump. marshal_load must recreate the object from the information in the result.
Example:
class MyObj def initialize name, version, data @name = name @version = version @data = data end def marshal_dump [@name, @version] end def marshal_load array @name, @version = array end end
Use _dump and _load when you need to allocate the object you’re restoring yourself.
When dumping an object the instance method _dump is called with an Integer
which indicates the maximum depth of objects to dump (a value of -1 implies that you should disable depth checking). _dump must return a String containing the information necessary to reconstitute the object.
The class method _load should take a String and use it to return an object of the same class.
Example:
class MyObj def initialize name, version, data @name = name @version = version @data = data end def _dump level [@name, @version].join ':' end def self._load args new(*args.split(':')) end end
Since Marshal.dump
outputs a string you can have _dump return a Marshal
string which is Marshal.loaded in _load for complex objects.
Many operating systems allow signals to be sent to running processes. Some signals have a defined effect on the process, while others may be trapped at the code level and acted upon. For example, your process may trap the USR1 signal and use it to toggle debugging, and may use TERM to initiate a controlled shutdown.
pid = fork do Signal.trap("USR1") do $debug = !$debug puts "Debug now: #$debug" end Signal.trap("TERM") do puts "Terminating..." shutdown() end # . . . do some work . . . end Process.detach(pid) # Controlling program: Process.kill("USR1", pid) # ... Process.kill("USR1", pid) # ... Process.kill("TERM", pid)
produces:
Debug now: true Debug now: false Terminating...
The list of available signal names and their interpretation is system dependent. Signal
delivery semantics may also vary between systems; in particular signal delivery may not always be reliable.
An InstalledSpecification
represents a gem that is already installed locally.
A set of gems for installation sourced from remote sources and local .gem files
Represents an installed gem. This is used for dependency resolution.
Extends Fiddle::Closure
to allow for building the closure in a block
Raised when a tar file is corrupt
This class is used as a return value from ObjectSpace::reachable_objects_from
.
When ObjectSpace::reachable_objects_from
returns an object with references to an internal object, an instance of this class is returned.
You can use the type
method to check the type of the internal object.
Scan scalars for built in types
Subclass of Zlib::Error
when zlib returns a Z_DATA_ERROR.
Usually if a stream was prematurely freed.