The Gem::Security
implements cryptographic signatures for gems. The section below is a step-by-step guide to using signed gems and generating your own.
In order to start signing your gems, you’ll need to build a private key and a self-signed certificate. Here’s how:
# build a private key and certificate for yourself: $ gem cert --build you@example.com
This could take anywhere from a few seconds to a minute or two, depending on the speed of your computer (public key algorithms aren’t exactly the speediest crypto algorithms in the world). When it’s finished, you’ll see the files “gem-private_key.pem” and “gem-public_cert.pem” in the current directory.
First things first: Move both files to ~/.gem if you don’t already have a key and certificate in that directory. Ensure the file permissions make the key unreadable by others (by default the file is saved securely).
Keep your private key hidden; if it’s compromised, someone can sign packages as you (note: PKI has ways of mitigating the risk of stolen keys; more on that later).
In RubyGems 2 and newer there is no extra work to sign a gem. RubyGems will automatically find your key and certificate in your home directory and use them to sign newly packaged gems.
If your certificate is not self-signed (signed by a third party) RubyGems will attempt to load the certificate chain from the trusted certificates. Use gem cert --add signing_cert.pem
to add your signers as trusted certificates. See below for further information on certificate chains.
If you build your gem it will automatically be signed. If you peek inside your gem file, you’ll see a couple of new files have been added:
$ tar tf your-gem-1.0.gem metadata.gz metadata.gz.sig # metadata signature data.tar.gz data.tar.gz.sig # data signature checksums.yaml.gz checksums.yaml.gz.sig # checksums signature
If you wish to store your key in a separate secure location you’ll need to set your gems up for signing by hand. To do this, set the signing_key
and cert_chain
in the gemspec before packaging your gem:
s.signing_key = '/secure/path/to/gem-private_key.pem' s.cert_chain = %w[/secure/path/to/gem-public_cert.pem]
When you package your gem with these options set RubyGems will automatically load your key and certificate from the secure paths.
Now let’s verify the signature. Go ahead and install the gem, but add the following options: -P HighSecurity
, like this:
# install the gem with using the security policy "HighSecurity" $ sudo gem install your.gem -P HighSecurity
The -P
option sets your security policy – we’ll talk about that in just a minute. Eh, what’s this?
$ gem install -P HighSecurity your-gem-1.0.gem ERROR: While executing gem ... (Gem::Security::Exception) root cert /CN=you/DC=example is not trusted
The culprit here is the security policy. RubyGems has several different security policies. Let’s take a short break and go over the security policies. Here’s a list of the available security policies, and a brief description of each one:
NoSecurity
- Well, no security at all. Signed packages are treated like unsigned packages.
LowSecurity
- Pretty much no security. If a package is signed then RubyGems will make sure the signature matches the signing certificate, and that the signing certificate hasn’t expired, but that’s it. A malicious user could easily circumvent this kind of security.
MediumSecurity
- Better than LowSecurity
and NoSecurity
, but still fallible. Package
contents are verified against the signing certificate, and the signing certificate is checked for validity, and checked against the rest of the certificate chain (if you don’t know what a certificate chain is, stay tuned, we’ll get to that). The biggest improvement over LowSecurity
is that MediumSecurity
won’t install packages that are signed by untrusted sources. Unfortunately, MediumSecurity
still isn’t totally secure – a malicious user can still unpack the gem, strip the signatures, and distribute the gem unsigned.
HighSecurity
- Here’s the bugger that got us into this mess. The HighSecurity
policy is identical to the MediumSecurity
policy, except that it does not allow unsigned gems. A malicious user doesn’t have a whole lot of options here; they can’t modify the package contents without invalidating the signature, and they can’t modify or remove signature or the signing certificate chain, or RubyGems will simply refuse to install the package. Oh well, maybe they’ll have better luck causing problems for CPAN users instead :).
The reason RubyGems refused to install your shiny new signed gem was because it was from an untrusted source. Well, your code is infallible (naturally), so you need to add yourself as a trusted source:
# add trusted certificate gem cert --add ~/.gem/gem-public_cert.pem
You’ve now added your public certificate as a trusted source. Now you can install packages signed by your private key without any hassle. Let’s try the install command above again:
# install the gem with using the HighSecurity policy (and this time # without any shenanigans) $ gem install -P HighSecurity your-gem-1.0.gem Successfully installed your-gem-1.0 1 gem installed
This time RubyGems will accept your signed package and begin installing.
While you’re waiting for RubyGems to work it’s magic, have a look at some of the other security commands by running gem help cert
:
Options: -a, --add CERT Add a trusted certificate. -l, --list [FILTER] List trusted certificates where the subject contains FILTER -r, --remove FILTER Remove trusted certificates where the subject contains FILTER -b, --build EMAIL_ADDR Build private key and self-signed certificate for EMAIL_ADDR -C, --certificate CERT Signing certificate for --sign -K, --private-key KEY Key for --sign or --build -A, --key-algorithm ALGORITHM Select key algorithm for --build from RSA, DSA, or EC. Defaults to RSA. -s, --sign CERT Signs CERT with the key from -K and the certificate from -C -d, --days NUMBER_OF_DAYS Days before the certificate expires -R, --re-sign Re-signs the certificate from -C with the key from -K
We’ve already covered the --build
option, and the --add
, --list
, and --remove
commands seem fairly straightforward; they allow you to add, list, and remove the certificates in your trusted certificate list. But what’s with this --sign
option?
To answer that question, let’s take a look at “certificate chains”, a concept I mentioned earlier. There are a couple of problems with self-signed certificates: first of all, self-signed certificates don’t offer a whole lot of security. Sure, the certificate says Yukihiro Matsumoto, but how do I know it was actually generated and signed by matz himself unless he gave me the certificate in person?
The second problem is scalability. Sure, if there are 50 gem authors, then I have 50 trusted certificates, no problem. What if there are 500 gem authors? 1000? Having to constantly add new trusted certificates is a pain, and it actually makes the trust system less secure by encouraging RubyGems users to blindly trust new certificates.
Here’s where certificate chains come in. A certificate chain establishes an arbitrarily long chain of trust between an issuing certificate and a child certificate. So instead of trusting certificates on a per-developer basis, we use the PKI concept of certificate chains to build a logical hierarchy of trust. Here’s a hypothetical example of a trust hierarchy based (roughly) on geography:
-------------------------- | rubygems@rubygems.org | -------------------------- | ----------------------------------- | | ---------------------------- ----------------------------- | seattlerb@seattlerb.org | | dcrubyists@richkilmer.com | ---------------------------- ----------------------------- | | | | --------------- ---------------- ----------- -------------- | drbrain | | zenspider | | pabs@dc | | tomcope@dc | --------------- ---------------- ----------- --------------
Now, rather than having 4 trusted certificates (one for drbrain, zenspider, pabs@dc, and tomecope@dc), a user could actually get by with one certificate, the “rubygems@rubygems.org” certificate.
Here’s how it works:
I install “rdoc-3.12.gem”, a package signed by “drbrain”. I’ve never heard of “drbrain”, but his certificate has a valid signature from the “seattle.rb@seattlerb.org” certificate, which in turn has a valid signature from the “rubygems@rubygems.org” certificate. Voila! At this point, it’s much more reasonable for me to trust a package signed by “drbrain”, because I can establish a chain to “rubygems@rubygems.org”, which I do trust.
The --sign
option allows all this to happen. A developer creates their build certificate with the --build
option, then has their certificate signed by taking it with them to their next regional Ruby meetup (in our hypothetical example), and it’s signed there by the person holding the regional RubyGems signing certificate, which is signed at the next RubyConf by the holder of the top-level RubyGems certificate. At each point the issuer runs the same command:
# sign a certificate with the specified key and certificate # (note that this modifies client_cert.pem!) $ gem cert -K /mnt/floppy/issuer-priv_key.pem -C issuer-pub_cert.pem --sign client_cert.pem
Then the holder of issued certificate (in this case, your buddy “drbrain”), can start using this signed certificate to sign RubyGems. By the way, in order to let everyone else know about his new fancy signed certificate, “drbrain” would save his newly signed certificate as ~/.gem/gem-public_cert.pem
Obviously this RubyGems trust infrastructure doesn’t exist yet. Also, in the “real world”, issuers actually generate the child certificate from a certificate request, rather than sign an existing certificate. And our hypothetical infrastructure is missing a certificate revocation system. These are that can be fixed in the future…
At this point you should know how to do all of these new and interesting things:
build a gem signing key and certificate
adjust your security policy
modify your trusted certificate list
sign a certificate
In case you don’t trust RubyGems you can verify gem signatures manually:
Fetch and unpack the gem
gem fetch some_signed_gem tar -xf some_signed_gem-1.0.gem
Grab the public key from the gemspec
gem spec some_signed_gem-1.0.gem cert_chain | \ ruby -rpsych -e 'puts Psych.load($stdin)' > public_key.crt
Generate a SHA1 hash of the data.tar.gz
openssl dgst -sha1 < data.tar.gz > my.hash
Verify the signature
openssl rsautl -verify -inkey public_key.crt -certin \ -in data.tar.gz.sig > verified.hash
Compare your hash to the verified hash
diff -s verified.hash my.hash
Repeat 5 and 6 with metadata.gz
OpenSSL
Reference The .pem files generated by –build and –sign are PEM files. Here’s a couple of useful OpenSSL
commands for manipulating them:
# convert a PEM format X509 certificate into DER format: # (note: Windows .cer files are X509 certificates in DER format) $ openssl x509 -in input.pem -outform der -out output.der # print out the certificate in a human-readable format: $ openssl x509 -in input.pem -noout -text
And you can do the same thing with the private key file as well:
# convert a PEM format RSA key into DER format: $ openssl rsa -in input_key.pem -outform der -out output_key.der # print out the key in a human readable format: $ openssl rsa -in input_key.pem -noout -text
There’s no way to define a system-wide trust list.
custom security policies (from a YAML
file, etc)
Simple method to generate a signed certificate request
Support for OCSP, SCVP, CRLs, or some other form of cert status check (list is in order of preference)
Support for encrypted private keys
Some sort of semi-formal trust hierarchy (see long-winded explanation above)
Path discovery (for gem certificate chains that don’t have a self-signed root) – by the way, since we don’t have this, THE ROOT OF THE CERTIFICATE CHAIN MUST BE SELF SIGNED if Policy#verify_root
is true (and it is for the MediumSecurity
and HighSecurity
policies)
Better explanation of X509 naming (ie, we don’t have to use email addresses)
Honor AIA field (see note about OCSP above)
Honor extension restrictions
Might be better to store the certificate chain as a PKCS#7 or PKCS#12 file, instead of an array embedded in the metadata.
Paul Duncan <pabs@pablotron.org> pablotron.org/
Mixin methods for security option for Gem::Commands
Numeric
is the class from which all higher-level numeric classes should inherit.
Numeric
allows instantiation of heap-allocated objects. Other core numeric classes such as Integer
are implemented as immediates, which means that each Integer
is a single immutable object which is always passed by value.
a = 1 1.object_id == a.object_id #=> true
There can only ever be one instance of the integer 1
, for example. Ruby ensures this by preventing instantiation. If duplication is attempted, the same instance is returned.
Integer.new(1) #=> NoMethodError: undefined method `new' for Integer:Class 1.dup #=> 1 1.object_id == 1.dup.object_id #=> true
For this reason, Numeric
should be used when defining other numeric classes.
Classes which inherit from Numeric
must implement coerce
, which returns a two-member Array
containing an object that has been coerced into an instance of the new class and self
(see coerce
).
Inheriting classes should also implement arithmetic operator methods (+
, -
, *
and /
) and the <=>
operator (see Comparable
). These methods may rely on coerce
to ensure interoperability with instances of other numeric classes.
class Tally < Numeric def initialize(string) @string = string end def to_s @string end def to_i @string.size end def coerce(other) [self.class.new('|' * other.to_i), self] end def <=>(other) to_i <=> other.to_i end def +(other) self.class.new('|' * (to_i + other.to_i)) end def -(other) self.class.new('|' * (to_i - other.to_i)) end def *(other) self.class.new('|' * (to_i * other.to_i)) end def /(other) self.class.new('|' * (to_i / other.to_i)) end end tally = Tally.new('||') puts tally * 2 #=> "||||" puts tally > 1 #=> true
First, what’s elsewhere. Class Numeric:
Inherits from class Object.
Includes module Comparable.
Here, class Numeric provides methods for:
finite?
: Returns true unless self
is infinite or not a number.
infinite?
: Returns -1, nil
or +1, depending on whether self
is -Infinity<tt>, finite, or <tt>+Infinity
.
integer?
: Returns whether self
is an integer.
negative?
: Returns whether self
is negative.
nonzero?
: Returns whether self
is not zero.
positive?
: Returns whether self
is positive.
real?
: Returns whether self
is a real value.
zero?
: Returns whether self
is zero.
<=>
: Returns:
-1 if self
is less than the given value.
0 if self
is equal to the given value.
1 if self
is greater than the given value.
nil
if self
and the given value are not comparable.
eql?
: Returns whether self
and the given value have the same value and type.
%
(aliased as modulo
): Returns the remainder of self
divided by the given value.
-@
: Returns the value of self
, negated.
abs
(aliased as magnitude
): Returns the absolute value of self
.
abs2
: Returns the square of self
.
angle
(aliased as arg
and phase
): Returns 0 if self
is positive, Math::PI otherwise.
ceil
: Returns the smallest number greater than or equal to self
, to a given precision.
coerce
: Returns array [coerced_self, coerced_other]
for the given other value.
conj
(aliased as conjugate
): Returns the complex conjugate of self
.
denominator
: Returns the denominator (always positive) of the Rational
representation of self
.
div
: Returns the value of self
divided by the given value and converted to an integer.
divmod
: Returns array [quotient, modulus]
resulting from dividing self
the given divisor.
fdiv
: Returns the Float
result of dividing self
by the given divisor.
floor
: Returns the largest number less than or equal to self
, to a given precision.
i
: Returns the Complex
object Complex(0, self)
. the given value.
imaginary
(aliased as imag
): Returns the imaginary part of the self
.
numerator
: Returns the numerator of the Rational
representation of self
; has the same sign as self
.
polar
: Returns the array [self.abs, self.arg]
.
quo
: Returns the value of self
divided by the given value.
real
: Returns the real part of self
.
rect
(aliased as rectangular
): Returns the array [self, 0]
.
remainder
: Returns self-arg*(self/arg).truncate
for the given arg
.
round
: Returns the value of self
rounded to the nearest value for the given a precision.
to_int
: Returns the Integer
representation of self
, truncating if necessary.
truncate
: Returns self
truncated (toward zero) to a given precision.
A String object has an arbitrary sequence of bytes, typically representing text or binary data. A String object may be created using String::new
or as literals.
String
objects differ from Symbol
objects in that Symbol
objects are designed to be used as identifiers, instead of text or data.
You can create a String object explicitly with:
A string literal.
A string literal.
You can convert certain objects to Strings with:
Method String
.
Some String methods modify self
. Typically, a method whose name ends with !
modifies self
and returns self
; often a similarly named method (without the !
) returns a new string.
In general, if there exist both bang and non-bang version of method, the bang! mutates and the non-bang! does not. However, a method without a bang can also mutate, such as String#replace
.
These methods perform substitutions:
String#sub
: One substitution (or none); returns a new string.
String#sub!
: One substitution (or none); returns self
.
String#gsub
: Zero or more substitutions; returns a new string.
String#gsub!
: Zero or more substitutions; returns self
.
Each of these methods takes:
A first argument, pattern
(string or regexp), that specifies the substring(s) to be replaced.
Either of these:
A second argument, replacement
(string or hash), that determines the replacing string.
A block that will determine the replacing string.
The examples in this section mostly use methods String#sub
and String#gsub
; the principles illustrated apply to all four substitution methods.
Argument pattern
Argument pattern
is commonly a regular expression:
s = 'hello' s.sub(/[aeiou]/, '*')# => "h*llo" s.gsub(/[aeiou]/, '*') # => "h*ll*" s.gsub(/[aeiou]/, '')# => "hll" s.sub(/ell/, 'al') # => "halo" s.gsub(/xyzzy/, '*') # => "hello" 'THX1138'.gsub(/\d+/, '00') # => "THX00"
When pattern
is a string, all its characters are treated as ordinary characters (not as regexp special characters):
'THX1138'.gsub('\d+', '00') # => "THX1138"
String replacement
If replacement
is a string, that string will determine the replacing string that is to be substituted for the matched text.
Each of the examples above uses a simple string as the replacing string.
String replacement
may contain back-references to the pattern’s captures:
\n
(n a non-negative integer) refers to $n
.
\k<name>
refers to the named capture name
.
See regexp.rdoc for details.
Note that within the string replacement
, a character combination such as $&
is treated as ordinary text, and not as a special match variable. However, you may refer to some special match variables using these combinations:
\&
and \0
correspond to $&
, which contains the complete matched text.
\'
corresponds to $'
, which contains string after match.
\`
corresponds to $`
, which contains string before match.
+
corresponds to $+
, which contains last capture group.
See regexp.rdoc for details.
Note that \\
is interpreted as an escape, i.e., a single backslash.
Note also that a string literal consumes backslashes. See string literal for details about string literals.
A back-reference is typically preceded by an additional backslash. For example, if you want to write a back-reference \&
in replacement
with a double-quoted string literal, you need to write "..\\&.."
.
If you want to write a non-back-reference string \&
in replacement
, you need first to escape the backslash to prevent this method from interpreting it as a back-reference, and then you need to escape the backslashes again to prevent a string literal from consuming them: "..\\\\&.."
.
You may want to use the block form to avoid a lot of backslashes.
Hash replacement
If argument replacement
is a hash, and pattern
matches one of its keys, the replacing string is the value for that key:
h = {'foo' => 'bar', 'baz' => 'bat'} 'food'.sub('foo', h) # => "bard"
Note that a symbol key does not match:
h = {foo: 'bar', baz: 'bat'} 'food'.sub('foo', h) # => "d"
Block
In the block form, the current match string is passed to the block; the block’s return value becomes the replacing string:
s = '@' '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD"
Special match variables such as $1
, $2
, $`
, $&
, and $'
are set appropriately.
In class String, whitespace is defined as a contiguous sequence of characters consisting of any mixture of the following:
NL (null): "\x00"
, "\u0000"
.
HT (horizontal tab): "\x09"
, "\t"
.
LF (line feed): "\x0a"
, "\n"
.
VT (vertical tab): "\x0b"
, "\v"
.
FF (form feed): "\x0c"
, "\f"
.
CR (carriage return): "\x0d"
, "\r"
.
SP (space): "\x20"
, " "
.
Whitespace is relevant for these methods:
A slice of a string is a substring that is selected by certain criteria.
These instance methods make use of slicing:
String#[]
(also aliased as String#slice
) returns a slice copied from self
.
String#[]=
returns a copy of self
with a slice replaced.
String#slice!
returns self
with a slice removed.
Each of the above methods takes arguments that determine the slice to be copied or replaced.
The arguments have several forms. For string string
, the forms are:
string[index]
.
string[start, length]
.
string[range]
.
string[regexp, capture = 0]
.
string[substring]
.
string[index]
When non-negative integer argument index
is given, the slice is the 1-character substring found in self
at character offset index
:
'bar'[0] # => "b" 'bar'[2] # => "r" 'bar'[20] # => nil 'тест'[2] # => "с" 'こんにちは'[4] # => "は"
When negative integer index
is given, the slice begins at the offset given by counting backward from the end of self
:
'bar'[-3] # => "b" 'bar'[-1] # => "r" 'bar'[-20] # => nil
string[start, length]
When non-negative integer arguments start
and length
are given, the slice begins at character offset start
, if it exists, and continues for length
characters, if available:
'foo'[0, 2] # => "fo" 'тест'[1, 2] # => "ес" 'こんにちは'[2, 2] # => "にち" # Zero length. 'foo'[2, 0] # => "" # Length not entirely available. 'foo'[1, 200] # => "oo" # Start out of range. 'foo'[4, 2] # => nil
Special case: if start
is equal to the length of self
, the slice is a new empty string:
'foo'[3, 2] # => "" 'foo'[3, 200] # => ""
When negative start
and non-negative length
are given, the slice beginning is determined by counting backward from the end of self
, and the slice continues for length
characters, if available:
'foo'[-2, 2] # => "oo" 'foo'[-2, 200] # => "oo" # Start out of range. 'foo'[-4, 2] # => nil
When negative length
is given, there is no slice:
'foo'[1, -1] # => nil 'foo'[-2, -1] # => nil
string[range]
When Range
argument range
is given, creates a substring of string
using the indices in range
. The slice is then determined as above:
'foo'[0..1] # => "fo" 'foo'[0, 2] # => "fo" 'foo'[2...2] # => "" 'foo'[2, 0] # => "" 'foo'[1..200] # => "oo" 'foo'[1, 200] # => "oo" 'foo'[4..5] # => nil 'foo'[4, 2] # => nil 'foo'[-4..-3] # => nil 'foo'[-4, 2] # => nil 'foo'[3..4] # => "" 'foo'[3, 2] # => "" 'foo'[-2..-1] # => "oo" 'foo'[-2, 2] # => "oo" 'foo'[-2..197] # => "oo" 'foo'[-2, 200] # => "oo"
string[regexp, capture = 0]
When the Regexp argument regexp
is given, and the capture
argument is 0
, the slice is the first matching substring found in self
:
'foo'[/o/] # => "o" 'foo'[/x/] # => nil s = 'hello there' s[/[aeiou](.)\1/] # => "ell" s[/[aeiou](.)\1/, 0] # => "ell"
If argument capture
is given and not 0
, it should be either an capture group index (integer) or a capture group name (string or symbol); the slice is the specified capture (see Capturing at Regexp
):
s = 'hello there' s[/[aeiou](.)\1/, 1] # => "l" s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] # => "l" s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel] # => "e"
If an invalid capture group index is given, there is no slice. If an invalid capture group name is given, IndexError
is raised.
string[substring]
When the single String argument substring
is given, returns the substring from self
if found, otherwise nil
:
'foo'['oo'] # => "oo" 'foo'['xx'] # => nil
First, what’s elsewhere. Class String:
Inherits from class Object.
Includes module Comparable.
Here, class String provides methods that are useful for:
::new
: Returns a new string.
::try_convert
: Returns a new string created from a given object.
String
+@
: Returns a string that is not frozen: self
, if not frozen; self.dup
otherwise.
-@
: Returns a string that is frozen: self
, if already frozen; self.freeze
otherwise.
freeze
: Freezes self
, if not already frozen; returns self
.
Counts
empty?
: Returns true
if self.length
is zero; false
otherwise.
bytesize
: Returns the count of bytes.
count
: Returns the count of substrings matching given strings.
Substrings
=~
: Returns the index of the first substring that matches a given Regexp
or other object; returns nil
if no match is found.
index
: Returns the index of the first occurrence of a given substring; returns nil
if none found.
rindex
: Returns the index of the last occurrence of a given substring; returns nil
if none found.
include?
: Returns true
if the string contains a given substring; false
otherwise.
match
: Returns a MatchData
object if the string matches a given Regexp
; nil
otherwise.
match?
: Returns true
if the string matches a given Regexp
; false
otherwise.
start_with?
: Returns true
if the string begins with any of the given substrings.
end_with?
: Returns true
if the string ends with any of the given substrings.
Encodings
encoding
: Returns the Encoding
object that represents the encoding of the string.
unicode_normalized?
: Returns true
if the string is in Unicode normalized form; false
otherwise.
valid_encoding?
: Returns true
if the string contains only characters that are valid for its encoding.
ascii_only?
: Returns true
if the string has only ASCII characters; false
otherwise.
Other
sum
: Returns a basic checksum for the string: the sum of each byte.
hash
: Returns the integer hash code.
==
, ===
: Returns true
if a given other string has the same content as self
.
eql?
: Returns true
if the content is the same as the given other string.
<=>
: Returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp
: Ignoring case, returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp?
: Returns true
if the string is equal to a given string after Unicode case folding; false
otherwise.
Each of these methods modifies self
.
Insertion
insert
: Returns self
with a given string inserted at a given offset.
<<
: Returns self
concatenated with a given string or integer.
Substitution
sub!
: Replaces the first substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
gsub!
: Replaces each substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
succ!
, next!
: Returns self
modified to become its own successor.
replace
: Returns self
with its entire content replaced by a given string.
reverse!
: Returns self
with its characters in reverse order.
setbyte
: Sets the byte at a given integer offset to a given value; returns the argument.
tr!
: Replaces specified characters in self
with specified replacement characters; returns self
if any changes, nil
otherwise.
tr_s!
: Replaces specified characters in self
with specified replacement characters, removing duplicates from the substrings that were modified; returns self
if any changes, nil
otherwise.
Casing
capitalize!
: Upcases the initial character and downcases all others; returns self
if any changes, nil
otherwise.
downcase!
: Downcases all characters; returns self
if any changes, nil
otherwise.
upcase!
: Upcases all characters; returns self
if any changes, nil
otherwise.
swapcase!
: Upcases each downcase character and downcases each upcase character; returns self
if any changes, nil
otherwise.
Encoding
encode!
: Returns self
with all characters transcoded from one given encoding into another.
unicode_normalize!
: Unicode-normalizes self
; returns self
.
scrub!
: Replaces each invalid byte with a given character; returns self
.
force_encoding
: Changes the encoding to a given encoding; returns self
.
Deletion
clear
: Removes all content, so that self
is empty; returns self
.
slice!
, []=
: Removes a substring determined by a given index, start/length, range, regexp, or substring.
squeeze!
: Removes contiguous duplicate characters; returns self
.
delete!
: Removes characters as determined by the intersection of substring arguments.
lstrip!
: Removes leading whitespace; returns self
if any changes, nil
otherwise.
rstrip!
: Removes trailing whitespace; returns self
if any changes, nil
otherwise.
strip!
: Removes leading and trailing whitespace; returns self
if any changes, nil
otherwise.
chomp!
: Removes trailing record separator, if found; returns self
if any changes, nil
otherwise.
chop!
: Removes trailing newline characters if found; otherwise removes the last character; returns self
if any changes, nil
otherwise.
Each of these methods returns a new String based on self
, often just a modified copy of self
.
Extension
*
: Returns the concatenation of multiple copies of self
,
+
: Returns the concatenation of self
and a given other string.
center
: Returns a copy of self
centered between pad substring.
concat
: Returns the concatenation of self
with given other strings.
prepend
: Returns the concatenation of a given other string with self
.
ljust
: Returns a copy of self
of a given length, right-padded with a given other string.
rjust
: Returns a copy of self
of a given length, left-padded with a given other string.
Encoding
b
: Returns a copy of self
with ASCII-8BIT encoding.
scrub
: Returns a copy of self
with each invalid byte replaced with a given character.
unicode_normalize
: Returns a copy of self
with each character Unicode-normalized.
encode
: Returns a copy of self
with all characters transcoded from one given encoding into another.
Substitution
dump
: Returns a copy of self
with all non-printing characters replaced by xHH notation and all special characters escaped.
undump
: Returns a copy of self
with all \xNN
notation replace by \uNNNN
notation and all escaped characters unescaped.
sub
: Returns a copy of self
with the first substring matching a given pattern replaced with a given replacement string;.
gsub
: Returns a copy of self
with each substring that matches a given pattern replaced with a given replacement string.
succ
, next
: Returns the string that is the successor to self
.
reverse
: Returns a copy of self
with its characters in reverse order.
tr
: Returns a copy of self
with specified characters replaced with specified replacement characters.
tr_s
: Returns a copy of self
with specified characters replaced with specified replacement characters, removing duplicates from the substrings that were modified.
%
: Returns the string resulting from formatting a given object into self
Casing
capitalize
: Returns a copy of self
with the first character upcased and all other characters downcased.
downcase
: Returns a copy of self
with all characters downcased.
upcase
: Returns a copy of self
with all characters upcased.
swapcase
: Returns a copy of self
with all upcase characters downcased and all downcase characters upcased.
Deletion
delete
: Returns a copy of self
with characters removed
delete_prefix
: Returns a copy of self
with a given prefix removed.
delete_suffix
: Returns a copy of self
with a given suffix removed.
lstrip
: Returns a copy of self
with leading whitespace removed.
rstrip
: Returns a copy of self
with trailing whitespace removed.
strip
: Returns a copy of self
with leading and trailing whitespace removed.
chomp
: Returns a copy of self
with a trailing record separator removed, if found.
chop
: Returns a copy of self
with trailing newline characters or the last character removed.
squeeze
: Returns a copy of self
with contiguous duplicate characters removed.
[]
, slice
: Returns a substring determined by a given index, start/length, or range, or string.
byteslice
: Returns a substring determined by a given index, start/length, or range.
chr
: Returns the first character.
Duplication
to_s
, $to_str: If self
is a subclass of String, returns self
copied into a String; otherwise, returns self
.
Each of these methods converts the contents of self
to a non-String.
Characters, Bytes, and Clusters
bytes
: Returns an array of the bytes in self
.
chars
: Returns an array of the characters in self
.
codepoints
: Returns an array of the integer ordinals in self
.
getbyte
: Returns an integer byte as determined by a given index.
grapheme_clusters
: Returns an array of the grapheme clusters in self
.
Splitting
lines
: Returns an array of the lines in self
, as determined by a given record separator.
partition
: Returns a 3-element array determined by the first substring that matches a given substring or regexp,
rpartition
: Returns a 3-element array determined by the last substring that matches a given substring or regexp,
split
: Returns an array of substrings determined by a given delimiter – regexp or string – or, if a block given, passes those substrings to the block.
Matching
scan
: Returns an array of substrings matching a given regexp or string, or, if a block given, passes each matching substring to the block.
unpack
: Returns an array of substrings extracted from self
according to a given format.
unpack1
: Returns the first substring extracted from self
according to a given format.
Numerics
hex
: Returns the integer value of the leading characters, interpreted as hexadecimal digits.
oct
: Returns the integer value of the leading characters, interpreted as octal digits.
ord
: Returns the integer ordinal of the first character in self
.
to_i
: Returns the integer value of leading characters, interpreted as an integer.
to_f
: Returns the floating-point value of leading characters, interpreted as a floating-point number.
Strings and Symbols
inspect
: Returns copy of self
, enclosed in double-quotes, with special characters escaped.
each_byte
: Calls the given block with each successive byte in self
.
each_char
: Calls the given block with each successive character in self
.
each_codepoint
: Calls the given block with each successive integer codepoint in self
.
each_grapheme_cluster
: Calls the given block with each successive grapheme cluster in self
.
each_line
: Calls the given block with each successive line in self
, as determined by a given record separator.
upto
: Calls the given block with each string value returned by successive calls to succ
.
ScriptError
is the superclass for errors raised when a script can not be executed because of a LoadError
, NotImplementedError
or a SyntaxError
. Note these type of ScriptErrors
are not StandardError
and will not be rescued unless it is specified explicitly (or its ancestor Exception
).
Ripper
is a Ruby script parser.
You can get information from the parser with event-based style. Information such as abstract syntax trees or simple lexical analysis of the Ruby program.
Ripper
provides an easy interface for parsing your program into a symbolic expression tree (or S-expression).
Understanding the output of the parser may come as a challenge, it’s recommended you use PP
to format the output for legibility.
require 'ripper' require 'pp' pp Ripper.sexp('def hello(world) "Hello, #{world}!"; end') #=> [:program, [[:def, [:@ident, "hello", [1, 4]], [:paren, [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]], [:bodystmt, [[:string_literal, [:string_content, [:@tstring_content, "Hello, ", [1, 18]], [:string_embexpr, [[:var_ref, [:@ident, "world", [1, 27]]]]], [:@tstring_content, "!", [1, 33]]]]], nil, nil, nil]]]]
You can see in the example above, the expression starts with :program
.
From here, a method definition at :def
, followed by the method’s identifier :@ident
. After the method’s identifier comes the parentheses :paren
and the method parameters under :params
.
Next is the method body, starting at :bodystmt
(stmt
meaning statement), which contains the full definition of the method.
In our case, we’re simply returning a String
, so next we have the :string_literal
expression.
Within our :string_literal
you’ll notice two @tstring_content
, this is the literal part for Hello,
and !
. Between the two @tstring_content
statements is a :string_embexpr
, where embexpr is an embedded expression. Our expression consists of a local variable, or var_ref
, with the identifier (@ident
) of world
.
ruby 1.9 (support CVS HEAD only)
bison 1.28 or later (Other yaccs do not work)
Ruby License.
Minero Aoki
aamine@loveruby.net
IO streams for strings, with access similar to IO
; see IO
.
Examples on this page assume that StringIO has been required:
require 'stringio'
StringScanner
provides for lexical scanning operations on a String
. Here is an example of its usage:
require 'strscan' s = StringScanner.new('This is an example string') s.eos? # -> false p s.scan(/\w+/) # -> "This" p s.scan(/\w+/) # -> nil p s.scan(/\s+/) # -> " " p s.scan(/\s+/) # -> nil p s.scan(/\w+/) # -> "is" s.eos? # -> false p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "an" p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "example" p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "string" s.eos? # -> true p s.scan(/\s+/) # -> nil p s.scan(/\w+/) # -> nil
Scanning a string means remembering the position of a scan pointer, which is just an index. The point of scanning is to move forward a bit at a time, so matches are sought after the scan pointer; usually immediately after it.
Given the string “test string”, here are the pertinent scan pointer positions:
t e s t s t r i n g 0 1 2 ... 1 0
When you scan
for a pattern (a regular expression), the match must occur at the character after the scan pointer. If you use scan_until
, then the match can occur anywhere after the scan pointer. In both cases, the scan pointer moves just beyond the last character of the match, ready to scan again from the next character onwards. This is demonstrated by the example above.
Method
Categories There are other methods besides the plain scanners. You can look ahead in the string without actually scanning. You can access the most recent match. You can modify the string being scanned, reset or terminate the scanner, find out or change the position of the scan pointer, skip ahead, and so on.
beginning_of_line?
(#bol?
)
Data
There are aliases to several of the methods.
This class implements a pretty printing algorithm. It finds line breaks and nice indentations for grouped structure.
By default, the class assumes that primitive elements are strings and each byte in the strings have single column in width. But it can be used for other situations by giving suitable arguments for some methods:
newline object and space generation block for PrettyPrint.new
optional width argument for PrettyPrint#text
There are several candidate uses:
text formatting using proportional fonts
multibyte characters which has columns different to number of bytes
non-string formatting
Box based formatting?
Other (better) model/algorithm?
Report any bugs at bugs.ruby-lang.org
Christian Lindig, Strictly Pretty, March 2000, www.st.cs.uni-sb.de/~lindig/papers/#pretty
Philip Wadler, A prettier printer, March 1998, homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier
Tanaka Akira <akr@fsij.org>
A module to implement the Linda distributed computing paradigm in Ruby.
See the sample/drb/ directory in the Ruby distribution, from 1.8.2 onwards.
This library is an interface to secure random number generators which are suitable for generating session keys in HTTP cookies, etc.
You can use this library in your application by requiring it:
require 'securerandom'
It supports the following secure random number generators:
openssl
/dev/urandom
SecureRandom
is extended by the Random::Formatter
module which defines the following methods:
alphanumeric
base64
choose
hex
rand
random_bytes
random_number
urlsafe_base64
uuid
These methods are usable as class methods of SecureRandom
such as SecureRandom.hex
.
If a secure random number generator is not available, NotImplementedError
is raised.
Generates URL-encoded form data from given enum
.
This generates application/x-www-form-urlencoded data defined in HTML5 from given an Enumerable
object.
This internally uses URI.encode_www_form_component(str)
.
This method doesn’t convert the encoding of given items, so convert them before calling this method if you want to send data as other than original encoding or mixed encoding data. (Strings which are encoded in an HTML5 ASCII incompatible encoding are converted to UTF-8.)
This method doesn’t handle files. When you send a file, use multipart/form-data.
This refers url.spec.whatwg.org/#concept-urlencoded-serializer
URI.encode_www_form([["q", "ruby"], ["lang", "en"]]) #=> "q=ruby&lang=en" URI.encode_www_form("q" => "ruby", "lang" => "en") #=> "q=ruby&lang=en" URI.encode_www_form("q" => ["ruby", "perl"], "lang" => "en") #=> "q=ruby&q=perl&lang=en" URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]]) #=> "q=ruby&q=perl&lang=en"
Decodes URL-encoded form data from given str
.
This decodes application/x-www-form-urlencoded data and returns an array of key-value arrays.
This refers url.spec.whatwg.org/#concept-urlencoded-parser, so this supports only &-separator, and doesn’t support ;-separator.
ary = URI.decode_www_form("a=1&a=2&b=3") ary #=> [['a', '1'], ['a', '2'], ['b', '3']] ary.assoc('a').last #=> '1' ary.assoc('b').last #=> '3' ary.rassoc('a').last #=> '2' Hash[ary] #=> {"a"=>"2", "b"=>"3"}
SecHandle struct
Creates binary representations of a SecBufferDesc structure, including the SecBuffer contained inside.
Enumerator::ArithmeticSequence
is a subclass of Enumerator
, that is a representation of sequences of numbers with common difference. Instances of this class can be generated by the Range#step
and Numeric#step
methods.
The class can be used for slicing Array
(see Array#slice
) or custom collections.
An FFI closure wrapper, for handling callbacks.
closure = Class.new(Fiddle::Closure) { def call 10 end }.new(Fiddle::TYPE_INT, []) #=> #<#<Class:0x0000000150d308>:0x0000000150d240> func = Fiddle::Function.new(closure, [], Fiddle::TYPE_INT) #=> #<Fiddle::Function:0x00000001516e58> func.call #=> 10
FIXME: This isn’t documented in Nutshell.
Since MonitorMixin.new_cond
returns a ConditionVariable
, and the example above calls while_wait and signal, this class should be documented.
UDP/IP address information used by Socket.udp_server_loop
.