rbs 0.12.1 → 0.15.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/ruby.yml +1 -1
- data/.gitignore +0 -1
- data/CHANGELOG.md +31 -0
- data/Gemfile +3 -0
- data/README.md +8 -2
- data/Rakefile +2 -2
- data/Steepfile +1 -0
- data/bin/annotate-with-rdoc +1 -1
- data/bin/setup +0 -2
- data/docs/CONTRIBUTING.md +1 -0
- data/docs/syntax.md +50 -6
- data/goodcheck.yml +22 -5
- data/lib/rbs/ast/comment.rb +1 -1
- data/lib/rbs/cli.rb +12 -4
- data/lib/rbs/constant.rb +1 -1
- data/lib/rbs/constant_table.rb +9 -8
- data/lib/rbs/definition_builder.rb +6 -7
- data/lib/rbs/environment.rb +5 -1
- data/lib/rbs/environment_loader.rb +12 -12
- data/lib/rbs/namespace.rb +1 -1
- data/lib/rbs/parser.rb +3148 -0
- data/lib/rbs/parser.y +10 -3
- data/lib/rbs/prototype/rb.rb +38 -6
- data/lib/rbs/prototype/runtime.rb +17 -7
- data/lib/rbs/test/hook.rb +2 -0
- data/lib/rbs/test/setup_helper.rb +4 -4
- data/lib/rbs/test/tester.rb +4 -1
- data/lib/rbs/test/type_check.rb +12 -6
- data/lib/rbs/type_name.rb +1 -1
- data/lib/rbs/variance_calculator.rb +2 -2
- data/lib/rbs/version.rb +1 -1
- data/lib/rbs/writer.rb +25 -15
- data/sig/constant.rbs +21 -0
- data/sig/constant_table.rbs +30 -0
- data/sig/declarations.rbs +2 -2
- data/sig/definition.rbs +2 -2
- data/sig/definition_builder.rbs +4 -5
- data/sig/environment_loader.rbs +54 -0
- data/sig/members.rbs +2 -2
- data/sig/method_types.rbs +1 -1
- data/sig/namespace.rbs +4 -4
- data/sig/parser.rbs +25 -0
- data/sig/substitution.rbs +3 -3
- data/sig/typename.rbs +1 -1
- data/sig/types.rbs +1 -1
- data/sig/version.rbs +3 -0
- data/sig/writer.rbs +40 -0
- data/stdlib/base64/base64.rbs +1 -1
- data/stdlib/benchmark/benchmark.rbs +2 -2
- data/stdlib/builtin/array.rbs +124 -120
- data/stdlib/builtin/basic_object.rbs +54 -54
- data/stdlib/builtin/binding.rbs +42 -42
- data/stdlib/builtin/builtin.rbs +28 -0
- data/stdlib/builtin/class.rbs +33 -33
- data/stdlib/builtin/complex.rbs +90 -90
- data/stdlib/builtin/encoding.rbs +33 -33
- data/stdlib/builtin/enumerable.rbs +58 -52
- data/stdlib/builtin/enumerator.rbs +35 -35
- data/stdlib/builtin/errors.rbs +2 -2
- data/stdlib/builtin/exception.rbs +50 -50
- data/stdlib/builtin/false_class.rbs +6 -6
- data/stdlib/builtin/fiber.rbs +14 -14
- data/stdlib/builtin/fiber_error.rbs +1 -1
- data/stdlib/builtin/float.rbs +161 -161
- data/stdlib/builtin/gc.rbs +3 -3
- data/stdlib/builtin/hash.rbs +7 -7
- data/stdlib/builtin/io.rbs +88 -88
- data/stdlib/builtin/kernel.rbs +71 -153
- data/stdlib/builtin/match_data.rbs +1 -1
- data/stdlib/builtin/method.rbs +19 -19
- data/stdlib/builtin/module.rbs +13 -13
- data/stdlib/builtin/nil_class.rbs +20 -20
- data/stdlib/builtin/numeric.rbs +101 -101
- data/stdlib/builtin/object.rbs +173 -173
- data/stdlib/builtin/proc.rbs +91 -91
- data/stdlib/builtin/random.rbs +1 -1
- data/stdlib/builtin/range.rbs +3 -5
- data/stdlib/builtin/rational.rbs +83 -83
- data/stdlib/builtin/signal.rbs +7 -7
- data/stdlib/builtin/string.rbs +10 -10
- data/stdlib/builtin/string_io.rbs +8 -8
- data/stdlib/builtin/struct.rbs +1 -1
- data/stdlib/builtin/symbol.rbs +1 -1
- data/stdlib/builtin/thread.rbs +189 -189
- data/stdlib/builtin/thread_group.rbs +2 -2
- data/stdlib/builtin/true_class.rbs +10 -10
- data/stdlib/builtin/warning.rbs +1 -1
- data/stdlib/coverage/coverage.rbs +2 -2
- data/stdlib/csv/csv.rbs +1 -1
- data/stdlib/date/date.rbs +4 -4
- data/stdlib/date/date_time.rbs +1 -1
- data/stdlib/find/find.rbs +12 -12
- data/stdlib/logger/log_device.rbs +1 -1
- data/stdlib/logger/logger.rbs +1 -1
- data/stdlib/pathname/pathname.rbs +41 -39
- data/stdlib/pstore/pstore.rbs +287 -0
- data/stdlib/pty/pty.rbs +5 -29
- data/stdlib/tmpdir/tmpdir.rbs +12 -12
- data/stdlib/uri/generic.rbs +2 -2
- data/stdlib/uri/http.rbs +158 -0
- data/stdlib/uri/https.rbs +108 -0
- data/stdlib/uri/ldap.rbs +224 -0
- data/stdlib/uri/ldaps.rbs +108 -0
- data/steep/Gemfile.lock +13 -17
- metadata +13 -3
@@ -1,11 +1,11 @@
|
|
1
1
|
# [ThreadGroup](ThreadGroup) provides a means of
|
2
2
|
# keeping track of a number of threads as a group.
|
3
|
-
#
|
3
|
+
#
|
4
4
|
# A given [Thread](https://ruby-doc.org/core-2.6.3/Thread.html) object can
|
5
5
|
# only belong to one [ThreadGroup](ThreadGroup) at a
|
6
6
|
# time; adding a thread to a new group will remove it from any previous
|
7
7
|
# group.
|
8
|
-
#
|
8
|
+
#
|
9
9
|
# Newly created threads belong to the same group as the thread from which
|
10
10
|
# they were created.
|
11
11
|
class ThreadGroup < Object
|
@@ -1,14 +1,14 @@
|
|
1
1
|
# The global value `true` is the only instance of class TrueClass and represents
|
2
2
|
# a logically true value in boolean expressions. The class provides operators
|
3
3
|
# allowing `true` to be used in logical expressions.
|
4
|
-
#
|
4
|
+
#
|
5
5
|
class TrueClass
|
6
6
|
public
|
7
7
|
|
8
8
|
def !: () -> bool
|
9
9
|
|
10
10
|
# And---Returns `false` if *obj* is `nil` or `false`, `true` otherwise.
|
11
|
-
#
|
11
|
+
#
|
12
12
|
def &: (nil) -> false
|
13
13
|
| (false) -> false
|
14
14
|
| (untyped obj) -> bool
|
@@ -16,12 +16,12 @@ class TrueClass
|
|
16
16
|
# Case Equality -- For class Object, effectively the same as calling `#==`, but
|
17
17
|
# typically overridden by descendants to provide meaningful semantics in `case`
|
18
18
|
# statements.
|
19
|
-
#
|
19
|
+
#
|
20
20
|
def ===: (true) -> true
|
21
21
|
| (untyped obj) -> bool
|
22
22
|
|
23
23
|
# Exclusive Or---Returns `true` if *obj* is `nil` or `false`, `false` otherwise.
|
24
|
-
#
|
24
|
+
#
|
25
25
|
def ^: (nil) -> true
|
26
26
|
| (false) -> true
|
27
27
|
| (untyped obj) -> bool
|
@@ -29,18 +29,18 @@ class TrueClass
|
|
29
29
|
alias inspect to_s
|
30
30
|
|
31
31
|
# The string representation of `true` is "true".
|
32
|
-
#
|
32
|
+
#
|
33
33
|
def to_s: () -> "true"
|
34
34
|
|
35
35
|
# Or---Returns `true`. As *obj* is an argument to a method call, it is always
|
36
36
|
# evaluated; there is no short-circuit evaluation in this case.
|
37
|
-
#
|
37
|
+
#
|
38
38
|
# true | puts("or")
|
39
39
|
# true || puts("logical or")
|
40
|
-
#
|
40
|
+
#
|
41
41
|
# *produces:*
|
42
|
-
#
|
42
|
+
#
|
43
43
|
# or
|
44
|
-
#
|
45
|
-
def |: (
|
44
|
+
#
|
45
|
+
def |: (boolish obj) -> bool
|
46
46
|
end
|
data/stdlib/builtin/warning.rbs
CHANGED
@@ -3,7 +3,7 @@
|
|
3
3
|
# module extends itself, making `Warning.warn` available.
|
4
4
|
# [\#warn](Warning#method-i-warn) is called for all
|
5
5
|
# warnings issued by Ruby. By default, warnings are printed to $stderr.
|
6
|
-
#
|
6
|
+
#
|
7
7
|
# By overriding [\#warn](Warning#method-i-warn), you
|
8
8
|
# can change how warnings are handled by Ruby, either filtering some
|
9
9
|
# warnings, and/or outputting warnings somewhere other than $stderr. When
|
@@ -49,7 +49,7 @@ module Coverage
|
|
49
49
|
# `clear` is true, it clears the counters to zero. If `stop` is true, it
|
50
50
|
# disables coverage measurement.
|
51
51
|
#
|
52
|
-
def self.result: (?stop:
|
52
|
+
def self.result: (?stop: boolish, ?clear: boolish) -> Hash[String, untyped]
|
53
53
|
|
54
54
|
# Returns true if coverage stats are currently being collected (after
|
55
55
|
# Coverage.start call, but before Coverage.result call)
|
@@ -58,5 +58,5 @@ module Coverage
|
|
58
58
|
|
59
59
|
# Enables coverage measurement.
|
60
60
|
#
|
61
|
-
def self.start: (?lines:
|
61
|
+
def self.start: (?lines: boolish, ?branches: boolish, ?methods: boolish, ?oneshot_lines: boolish) -> nil
|
62
62
|
end
|
data/stdlib/csv/csv.rbs
CHANGED
@@ -755,7 +755,7 @@ class CSV::Table[out Elem] < Object
|
|
755
755
|
# This method assumes you want the Table.headers(), unless you explicitly pass
|
756
756
|
# `:write_headers => false`.
|
757
757
|
#
|
758
|
-
def to_csv: (?write_headers:
|
758
|
+
def to_csv: (?write_headers: boolish, **untyped) -> untyped
|
759
759
|
|
760
760
|
alias to_s to_csv
|
761
761
|
|
data/stdlib/date/date.rbs
CHANGED
@@ -178,7 +178,7 @@ class Date
|
|
178
178
|
#
|
179
179
|
# Date._parse('2001-02-03') #=> {:year=>2001, :mon=>2, :mday=>3}
|
180
180
|
#
|
181
|
-
def self._parse: (String str, ?
|
181
|
+
def self._parse: (String str, ?boolish complete) -> Hash[Symbol, Integer]
|
182
182
|
|
183
183
|
# Returns a hash of parsed elements.
|
184
184
|
#
|
@@ -318,7 +318,7 @@ class Date
|
|
318
318
|
#
|
319
319
|
def self.ordinal: (?Integer year, ?Integer yday, ?Integer start) -> Date
|
320
320
|
|
321
|
-
# Parses the given representation of date and time, and creates a date object.
|
321
|
+
# Parses the given representation of date and time, and creates a date object.
|
322
322
|
# This method does not function as a validator.
|
323
323
|
#
|
324
324
|
# If the optional second argument is true and the detected year is in the range
|
@@ -328,7 +328,7 @@ class Date
|
|
328
328
|
# Date.parse('20010203') #=> #<Date: 2001-02-03 ...>
|
329
329
|
# Date.parse('3rd Feb 2001') #=> #<Date: 2001-02-03 ...>
|
330
330
|
#
|
331
|
-
def self.parse: (String str, ?
|
331
|
+
def self.parse: (String str, ?boolish complete, ?Integer start) -> Date
|
332
332
|
|
333
333
|
# Creates a new Date object by parsing from a string according to some typical
|
334
334
|
# RFC 2822 formats.
|
@@ -448,7 +448,7 @@ class Date
|
|
448
448
|
#
|
449
449
|
def +: (Integer | Rational other) -> Date
|
450
450
|
|
451
|
-
# Returns the difference between the two dates if the other is a date object.
|
451
|
+
# Returns the difference between the two dates if the other is a date object.
|
452
452
|
# If the other is a numeric value, returns a date object pointing `other` days
|
453
453
|
# before self. If the other is a fractional number, assumes its precision is at
|
454
454
|
# most nanosecond.
|
data/stdlib/date/date_time.rbs
CHANGED
@@ -236,7 +236,7 @@ class DateTime < Date
|
|
236
236
|
# DateTime.parse('3rd Feb 2001 04:05:06 PM')
|
237
237
|
# #=> #<DateTime: 2001-02-03T16:05:06+00:00 ...>
|
238
238
|
#
|
239
|
-
def self.parse: (String str, ?
|
239
|
+
def self.parse: (String str, ?boolish complete, ?Integer start) -> DateTime
|
240
240
|
|
241
241
|
# Creates a new DateTime object by parsing from a string according to some
|
242
242
|
# typical RFC 2822 formats.
|
data/stdlib/find/find.rbs
CHANGED
@@ -1,12 +1,12 @@
|
|
1
1
|
# The `Find` module supports the top-down traversal of a set of file paths.
|
2
|
-
#
|
2
|
+
#
|
3
3
|
# For example, to total the size of all files under your home directory,
|
4
4
|
# ignoring anything in a "dot" directory (e.g. $HOME/.ssh):
|
5
|
-
#
|
5
|
+
#
|
6
6
|
# require 'find'
|
7
|
-
#
|
7
|
+
#
|
8
8
|
# total_size = 0
|
9
|
-
#
|
9
|
+
#
|
10
10
|
# Find.find(ENV["HOME"]) do |path|
|
11
11
|
# if FileTest.directory?(path)
|
12
12
|
# if File.basename(path).start_with?('.')
|
@@ -18,23 +18,23 @@
|
|
18
18
|
# total_size += FileTest.size(path)
|
19
19
|
# end
|
20
20
|
# end
|
21
|
-
#
|
21
|
+
#
|
22
22
|
module Find
|
23
23
|
# Calls the associated block with the name of every file and directory listed as
|
24
24
|
# arguments, then recursively on their subdirectories, and so on.
|
25
|
-
#
|
25
|
+
#
|
26
26
|
# Returns an enumerator if no block is given.
|
27
|
-
#
|
27
|
+
#
|
28
28
|
# See the `Find` module documentation for an example.
|
29
|
-
#
|
30
|
-
def self?.find: (*String | _ToPath paths, ?ignore_error:
|
31
|
-
| (*String | _ToPath paths, ?ignore_error:
|
29
|
+
#
|
30
|
+
def self?.find: (*String | _ToPath paths, ?ignore_error: boolish) -> Enumerator[String, nil]
|
31
|
+
| (*String | _ToPath paths, ?ignore_error: boolish) { (String) -> void } -> nil
|
32
32
|
|
33
33
|
# Skips the current file or directory, restarting the loop with the next entry.
|
34
34
|
# If the current file is a directory, that directory will not be recursively
|
35
35
|
# entered. Meaningful only within the block associated with Find::find.
|
36
|
-
#
|
36
|
+
#
|
37
37
|
# See the `Find` module documentation for an example.
|
38
|
-
#
|
38
|
+
#
|
39
39
|
def self?.prune: () -> void
|
40
40
|
end
|
@@ -24,7 +24,7 @@ class Logger
|
|
24
24
|
|
25
25
|
def create_logfile: (String filename) -> File
|
26
26
|
|
27
|
-
def initialize: (?untyped logdev, ?binmode:
|
27
|
+
def initialize: (?untyped logdev, ?binmode: boolish, ?shift_period_suffix: String, ?shift_size: Integer, ?shift_age: Numeric | String) -> void
|
28
28
|
|
29
29
|
def lock_shift_log: () { () -> untyped } -> untyped
|
30
30
|
|
data/stdlib/logger/logger.rbs
CHANGED
@@ -495,7 +495,7 @@ class Logger
|
|
495
495
|
#
|
496
496
|
# Create an instance.
|
497
497
|
#
|
498
|
-
def initialize: (logdev logdev, ?Numeric | String shift_age, ?Integer shift_size, ?shift_period_suffix: String, ?binmode:
|
498
|
+
def initialize: (logdev logdev, ?Numeric | String shift_age, ?Integer shift_size, ?shift_period_suffix: String, ?binmode: boolish, ?datetime_format: String, ?formatter: _Formatter, ?progname: String, ?level: Integer) -> void
|
499
499
|
end
|
500
500
|
|
501
501
|
Logger::ProgName: String
|
@@ -324,9 +324,9 @@ class Pathname
|
|
324
324
|
?external_encoding: encoding,
|
325
325
|
?internal_encoding: encoding,
|
326
326
|
?encoding: encoding,
|
327
|
-
?textmode:
|
328
|
-
?binmode:
|
329
|
-
?autoclose:
|
327
|
+
?textmode: boolish,
|
328
|
+
?binmode: boolish,
|
329
|
+
?autoclose: boolish,
|
330
330
|
|
331
331
|
# From String#encode
|
332
332
|
?invalid: :replace ?,
|
@@ -373,7 +373,7 @@ class Pathname
|
|
373
373
|
# Note that the results never contain the entries `.` and `..` in the directory
|
374
374
|
# because they are not children.
|
375
375
|
#
|
376
|
-
def children: (?
|
376
|
+
def children: (?boolish with_directory) -> untyped
|
377
377
|
|
378
378
|
# Changes file permissions.
|
379
379
|
#
|
@@ -397,7 +397,7 @@ class Pathname
|
|
397
397
|
#
|
398
398
|
# See Pathname#realpath.
|
399
399
|
#
|
400
|
-
def cleanpath: (?
|
400
|
+
def cleanpath: (?boolish consider_symlink) -> Pathname
|
401
401
|
|
402
402
|
# Returns the last change time, using directory information, not the file
|
403
403
|
# itself.
|
@@ -485,8 +485,8 @@ class Pathname
|
|
485
485
|
#
|
486
486
|
# See Pathname#children
|
487
487
|
#
|
488
|
-
def each_child: (?
|
489
|
-
| (?
|
488
|
+
def each_child: (?boolish with_directory) { (Pathname) -> void } -> Array[Pathname]
|
489
|
+
| (?boolish with_directory) -> Enumerator[Pathname, Array[Pathname]]
|
490
490
|
|
491
491
|
# Iterates over the entries (files and subdirectories) in the directory,
|
492
492
|
# yielding a Pathname object for each entry.
|
@@ -517,11 +517,11 @@ class Pathname
|
|
517
517
|
?external_encoding: encoding,
|
518
518
|
?internal_encoding: encoding,
|
519
519
|
?encoding: encoding,
|
520
|
-
?textmode:
|
521
|
-
?binmode:
|
522
|
-
?autoclose:
|
520
|
+
?textmode: boolish,
|
521
|
+
?binmode: boolish,
|
522
|
+
?autoclose: boolish,
|
523
523
|
# getline_args
|
524
|
-
?chomp:
|
524
|
+
?chomp: boolish,
|
525
525
|
) { (String) -> untyped } -> nil
|
526
526
|
| (Integer limit,
|
527
527
|
# open_args
|
@@ -530,11 +530,11 @@ class Pathname
|
|
530
530
|
?external_encoding: encoding,
|
531
531
|
?internal_encoding: encoding,
|
532
532
|
?encoding: encoding,
|
533
|
-
?textmode:
|
534
|
-
?binmode:
|
535
|
-
?autoclose:
|
533
|
+
?textmode: boolish,
|
534
|
+
?binmode: boolish,
|
535
|
+
?autoclose: boolish,
|
536
536
|
# getline_args
|
537
|
-
?chomp:
|
537
|
+
?chomp: boolish,
|
538
538
|
) { (String) -> untyped } -> nil
|
539
539
|
| (?String sep, ?Integer limit,
|
540
540
|
# open_args
|
@@ -543,11 +543,11 @@ class Pathname
|
|
543
543
|
?external_encoding: encoding,
|
544
544
|
?internal_encoding: encoding,
|
545
545
|
?encoding: encoding,
|
546
|
-
?textmode:
|
547
|
-
?binmode:
|
548
|
-
?autoclose:
|
546
|
+
?textmode: boolish,
|
547
|
+
?binmode: boolish,
|
548
|
+
?autoclose: boolish,
|
549
549
|
# getline_args
|
550
|
-
?chomp:
|
550
|
+
?chomp: boolish,
|
551
551
|
) -> Enumerator[String, nil]
|
552
552
|
| (Integer limit,
|
553
553
|
# open_args
|
@@ -556,11 +556,11 @@ class Pathname
|
|
556
556
|
?external_encoding: encoding,
|
557
557
|
?internal_encoding: encoding,
|
558
558
|
?encoding: encoding,
|
559
|
-
?textmode:
|
560
|
-
?binmode:
|
561
|
-
?autoclose:
|
559
|
+
?textmode: boolish,
|
560
|
+
?binmode: boolish,
|
561
|
+
?autoclose: boolish,
|
562
562
|
# getline_args
|
563
|
-
?chomp:
|
563
|
+
?chomp: boolish,
|
564
564
|
) -> Enumerator[String, nil]
|
565
565
|
|
566
566
|
# Tests the file is empty.
|
@@ -643,8 +643,8 @@ class Pathname
|
|
643
643
|
#
|
644
644
|
# See Find.find
|
645
645
|
#
|
646
|
-
def find: (?ignore_error:
|
647
|
-
| (?ignore_error:
|
646
|
+
def find: (?ignore_error: boolish) { (Pathname) -> untyped } -> nil
|
647
|
+
| (?ignore_error: boolish) -> Enumerator[Pathname, nil]
|
648
648
|
|
649
649
|
# Return `true` if the receiver matches the given pattern.
|
650
650
|
#
|
@@ -789,9 +789,9 @@ class Pathname
|
|
789
789
|
?external_encoding: encoding,
|
790
790
|
?internal_encoding: encoding,
|
791
791
|
?encoding: encoding,
|
792
|
-
?textmode:
|
793
|
-
?binmode:
|
794
|
-
?autoclose:
|
792
|
+
?textmode: boolish,
|
793
|
+
?binmode: boolish,
|
794
|
+
?autoclose: boolish,
|
795
795
|
) -> String
|
796
796
|
|
797
797
|
# See FileTest.readable?.
|
@@ -813,11 +813,11 @@ class Pathname
|
|
813
813
|
?external_encoding: encoding,
|
814
814
|
?internal_encoding: encoding,
|
815
815
|
?encoding: encoding,
|
816
|
-
?textmode:
|
817
|
-
?binmode:
|
818
|
-
?autoclose:
|
816
|
+
?textmode: boolish,
|
817
|
+
?binmode: boolish,
|
818
|
+
?autoclose: boolish,
|
819
819
|
# getline_args
|
820
|
-
?chomp:
|
820
|
+
?chomp: boolish,
|
821
821
|
) -> Array[String]
|
822
822
|
| (Integer limit,
|
823
823
|
# open_args
|
@@ -826,11 +826,11 @@ class Pathname
|
|
826
826
|
?external_encoding: encoding,
|
827
827
|
?internal_encoding: encoding,
|
828
828
|
?encoding: encoding,
|
829
|
-
?textmode:
|
830
|
-
?binmode:
|
831
|
-
?autoclose:
|
829
|
+
?textmode: boolish,
|
830
|
+
?binmode: boolish,
|
831
|
+
?autoclose: boolish,
|
832
832
|
# getline_args
|
833
|
-
?chomp:
|
833
|
+
?chomp: boolish,
|
834
834
|
) -> Array[String]
|
835
835
|
|
836
836
|
# Read symbolic link.
|
@@ -1033,9 +1033,9 @@ class Pathname
|
|
1033
1033
|
?external_encoding: encoding,
|
1034
1034
|
?internal_encoding: encoding,
|
1035
1035
|
?encoding: encoding,
|
1036
|
-
?textmode:
|
1037
|
-
?binmode:
|
1038
|
-
?autoclose:
|
1036
|
+
?textmode: boolish,
|
1037
|
+
?binmode: boolish,
|
1038
|
+
?autoclose: boolish,
|
1039
1039
|
) -> Integer
|
1040
1040
|
|
1041
1041
|
# See FileTest.zero?.
|
@@ -1077,6 +1077,8 @@ class Pathname
|
|
1077
1077
|
end
|
1078
1078
|
|
1079
1079
|
module Kernel
|
1080
|
+
private
|
1081
|
+
|
1080
1082
|
# Creates a new Pathname object from the given string, `path`, and returns
|
1081
1083
|
# pathname object.
|
1082
1084
|
#
|
@@ -0,0 +1,287 @@
|
|
1
|
+
# PStore implements a file based persistence mechanism based on a Hash. User
|
2
|
+
# code can store hierarchies of Ruby objects (values) into the data store file
|
3
|
+
# by name (keys). An object hierarchy may be just a single object. User code
|
4
|
+
# may later read values back from the data store or even update data, as needed.
|
5
|
+
#
|
6
|
+
# The transactional behavior ensures that any changes succeed or fail together.
|
7
|
+
# This can be used to ensure that the data store is not left in a transitory
|
8
|
+
# state, where some values were updated but others were not.
|
9
|
+
#
|
10
|
+
# Behind the scenes, Ruby objects are stored to the data store file with
|
11
|
+
# Marshal. That carries the usual limitations. Proc objects cannot be
|
12
|
+
# marshalled, for example.
|
13
|
+
#
|
14
|
+
# ## Usage example:
|
15
|
+
#
|
16
|
+
# require "pstore"
|
17
|
+
#
|
18
|
+
# # a mock wiki object...
|
19
|
+
# class WikiPage
|
20
|
+
# def initialize( page_name, author, contents )
|
21
|
+
# @page_name = page_name
|
22
|
+
# @revisions = Array.new
|
23
|
+
#
|
24
|
+
# add_revision(author, contents)
|
25
|
+
# end
|
26
|
+
#
|
27
|
+
# attr_reader :page_name
|
28
|
+
#
|
29
|
+
# def add_revision( author, contents )
|
30
|
+
# @revisions << { :created => Time.now,
|
31
|
+
# :author => author,
|
32
|
+
# :contents => contents }
|
33
|
+
# end
|
34
|
+
#
|
35
|
+
# def wiki_page_references
|
36
|
+
# [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
|
37
|
+
# end
|
38
|
+
#
|
39
|
+
# # ...
|
40
|
+
# end
|
41
|
+
#
|
42
|
+
# # create a new page...
|
43
|
+
# home_page = WikiPage.new( "HomePage", "James Edward Gray II",
|
44
|
+
# "A page about the JoysOfDocumentation..." )
|
45
|
+
#
|
46
|
+
# # then we want to update page data and the index together, or not at all...
|
47
|
+
# wiki = PStore.new("wiki_pages.pstore")
|
48
|
+
# wiki.transaction do # begin transaction; do all of this or none of it
|
49
|
+
# # store page...
|
50
|
+
# wiki[home_page.page_name] = home_page
|
51
|
+
# # ensure that an index has been created...
|
52
|
+
# wiki[:wiki_index] ||= Array.new
|
53
|
+
# # update wiki index...
|
54
|
+
# wiki[:wiki_index].push(*home_page.wiki_page_references)
|
55
|
+
# end # commit changes to wiki data store file
|
56
|
+
#
|
57
|
+
# ### Some time later... ###
|
58
|
+
#
|
59
|
+
# # read wiki data...
|
60
|
+
# wiki.transaction(true) do # begin read-only transaction, no changes allowed
|
61
|
+
# wiki.roots.each do |data_root_name|
|
62
|
+
# p data_root_name
|
63
|
+
# p wiki[data_root_name]
|
64
|
+
# end
|
65
|
+
# end
|
66
|
+
#
|
67
|
+
# ## Transaction modes
|
68
|
+
#
|
69
|
+
# By default, file integrity is only ensured as long as the operating system
|
70
|
+
# (and the underlying hardware) doesn't raise any unexpected I/O errors. If an
|
71
|
+
# I/O error occurs while PStore is writing to its file, then the file will
|
72
|
+
# become corrupted.
|
73
|
+
#
|
74
|
+
# You can prevent this by setting *pstore.ultra_safe = true*. However, this
|
75
|
+
# results in a minor performance loss, and only works on platforms that support
|
76
|
+
# atomic file renames. Please consult the documentation for `ultra_safe` for
|
77
|
+
# details.
|
78
|
+
#
|
79
|
+
# Needless to say, if you're storing valuable data with PStore, then you should
|
80
|
+
# backup the PStore files from time to time.
|
81
|
+
#
|
82
|
+
class PStore
|
83
|
+
public
|
84
|
+
|
85
|
+
# Retrieves a value from the PStore file data, by *name*. The hierarchy of Ruby
|
86
|
+
# objects stored under that root *name* will be returned.
|
87
|
+
#
|
88
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
89
|
+
# raise PStore::Error if called at any other time.
|
90
|
+
#
|
91
|
+
def []: (untyped name) -> untyped
|
92
|
+
|
93
|
+
# Stores an individual Ruby object or a hierarchy of Ruby objects in the data
|
94
|
+
# store file under the root *name*. Assigning to a *name* already in the data
|
95
|
+
# store clobbers the old data.
|
96
|
+
#
|
97
|
+
# ## Example:
|
98
|
+
#
|
99
|
+
# require "pstore"
|
100
|
+
#
|
101
|
+
# store = PStore.new("data_file.pstore")
|
102
|
+
# store.transaction do # begin transaction
|
103
|
+
# # load some data into the store...
|
104
|
+
# store[:single_object] = "My data..."
|
105
|
+
# store[:obj_hierarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
|
106
|
+
# "James Gray" => ["erb.rb", "pstore.rb"] }
|
107
|
+
# end # commit changes to data store file
|
108
|
+
#
|
109
|
+
# **WARNING**: This method is only valid in a PStore#transaction and it cannot
|
110
|
+
# be read-only. It will raise PStore::Error if called at any other time.
|
111
|
+
#
|
112
|
+
def []=: (untyped name, untyped value) -> untyped
|
113
|
+
|
114
|
+
# Ends the current PStore#transaction, discarding any changes to the data store.
|
115
|
+
#
|
116
|
+
# ## Example:
|
117
|
+
#
|
118
|
+
# require "pstore"
|
119
|
+
#
|
120
|
+
# store = PStore.new("data_file.pstore")
|
121
|
+
# store.transaction do # begin transaction
|
122
|
+
# store[:one] = 1 # this change is not applied, see below...
|
123
|
+
# store[:two] = 2 # this change is not applied, see below...
|
124
|
+
#
|
125
|
+
# store.abort # end transaction here, discard all changes
|
126
|
+
#
|
127
|
+
# store[:three] = 3 # this change is never reached
|
128
|
+
# end
|
129
|
+
#
|
130
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
131
|
+
# raise PStore::Error if called at any other time.
|
132
|
+
#
|
133
|
+
def abort: () -> untyped
|
134
|
+
|
135
|
+
# Ends the current PStore#transaction, committing any changes to the data store
|
136
|
+
# immediately.
|
137
|
+
#
|
138
|
+
# ## Example:
|
139
|
+
#
|
140
|
+
# require "pstore"
|
141
|
+
#
|
142
|
+
# store = PStore.new("data_file.pstore")
|
143
|
+
# store.transaction do # begin transaction
|
144
|
+
# # load some data into the store...
|
145
|
+
# store[:one] = 1
|
146
|
+
# store[:two] = 2
|
147
|
+
#
|
148
|
+
# store.commit # end transaction here, committing changes
|
149
|
+
#
|
150
|
+
# store[:three] = 3 # this change is never reached
|
151
|
+
# end
|
152
|
+
#
|
153
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
154
|
+
# raise PStore::Error if called at any other time.
|
155
|
+
#
|
156
|
+
def commit: () -> nil
|
157
|
+
|
158
|
+
# Removes an object hierarchy from the data store, by *name*.
|
159
|
+
#
|
160
|
+
# **WARNING**: This method is only valid in a PStore#transaction and it cannot
|
161
|
+
# be read-only. It will raise PStore::Error if called at any other time.
|
162
|
+
#
|
163
|
+
def delete: (untyped name) -> untyped
|
164
|
+
|
165
|
+
# This method is just like PStore#[], save that you may also provide a *default*
|
166
|
+
# value for the object. In the event the specified *name* is not found in the
|
167
|
+
# data store, your *default* will be returned instead. If you do not specify a
|
168
|
+
# default, PStore::Error will be raised if the object is not found.
|
169
|
+
#
|
170
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
171
|
+
# raise PStore::Error if called at any other time.
|
172
|
+
#
|
173
|
+
def fetch: (untyped name, ?untyped default) -> untyped
|
174
|
+
|
175
|
+
# Returns the path to the data store file.
|
176
|
+
#
|
177
|
+
def path: () -> untyped
|
178
|
+
|
179
|
+
# Returns true if the supplied *name* is currently in the data store.
|
180
|
+
#
|
181
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
182
|
+
# raise PStore::Error if called at any other time.
|
183
|
+
#
|
184
|
+
def root?: (untyped name) -> bool
|
185
|
+
|
186
|
+
# Returns the names of all object hierarchies currently in the store.
|
187
|
+
#
|
188
|
+
# **WARNING**: This method is only valid in a PStore#transaction. It will
|
189
|
+
# raise PStore::Error if called at any other time.
|
190
|
+
#
|
191
|
+
def roots: () -> Array[untyped]
|
192
|
+
|
193
|
+
# Opens a new transaction for the data store. Code executed inside a block
|
194
|
+
# passed to this method may read and write data to and from the data store file.
|
195
|
+
#
|
196
|
+
# At the end of the block, changes are committed to the data store
|
197
|
+
# automatically. You may exit the transaction early with a call to either
|
198
|
+
# PStore#commit or PStore#abort. See those methods for details about how
|
199
|
+
# changes are handled. Raising an uncaught Exception in the block is equivalent
|
200
|
+
# to calling PStore#abort.
|
201
|
+
#
|
202
|
+
# If *read_only* is set to `true`, you will only be allowed to read from the
|
203
|
+
# data store during the transaction and any attempts to change the data will
|
204
|
+
# raise a PStore::Error.
|
205
|
+
#
|
206
|
+
# Note that PStore does not support nested transactions.
|
207
|
+
#
|
208
|
+
def transaction: (?untyped read_only) -> untyped
|
209
|
+
|
210
|
+
# Whether PStore should do its best to prevent file corruptions, even when under
|
211
|
+
# unlikely-to-occur error conditions such as out-of-space conditions and other
|
212
|
+
# unusual OS filesystem errors. Setting this flag comes at the price in the form
|
213
|
+
# of a performance loss.
|
214
|
+
#
|
215
|
+
# This flag only has effect on platforms on which file renames are atomic (e.g.
|
216
|
+
# all POSIX platforms: Linux, MacOS X, FreeBSD, etc). The default value is
|
217
|
+
# false.
|
218
|
+
#
|
219
|
+
def ultra_safe: () -> untyped
|
220
|
+
|
221
|
+
def ultra_safe=: (untyped) -> untyped
|
222
|
+
|
223
|
+
private
|
224
|
+
|
225
|
+
def dump: (untyped table) -> untyped
|
226
|
+
|
227
|
+
def empty_marshal_checksum: () -> untyped
|
228
|
+
|
229
|
+
def empty_marshal_data: () -> untyped
|
230
|
+
|
231
|
+
# Raises PStore::Error if the calling code is not in a PStore#transaction.
|
232
|
+
#
|
233
|
+
def in_transaction: () -> untyped
|
234
|
+
|
235
|
+
# Raises PStore::Error if the calling code is not in a PStore#transaction or if
|
236
|
+
# the code is in a read-only PStore#transaction.
|
237
|
+
#
|
238
|
+
def in_transaction_wr: () -> untyped
|
239
|
+
|
240
|
+
# To construct a PStore object, pass in the *file* path where you would like the
|
241
|
+
# data to be stored.
|
242
|
+
#
|
243
|
+
# PStore objects are always reentrant. But if *thread_safe* is set to true, then
|
244
|
+
# it will become thread-safe at the cost of a minor performance hit.
|
245
|
+
#
|
246
|
+
def initialize: (untyped file, ?boolish thread_safe) -> untyped
|
247
|
+
|
248
|
+
def load: (untyped content) -> untyped
|
249
|
+
|
250
|
+
# Load the given PStore file. If `read_only` is true, the unmarshalled Hash will
|
251
|
+
# be returned. If `read_only` is false, a 3-tuple will be returned: the
|
252
|
+
# unmarshalled Hash, a checksum of the data, and the size of the data.
|
253
|
+
#
|
254
|
+
def load_data: (untyped file, untyped read_only) -> untyped
|
255
|
+
|
256
|
+
def on_windows?: () -> bool
|
257
|
+
|
258
|
+
# Open the specified filename (either in read-only mode or in read-write mode)
|
259
|
+
# and lock it for reading or writing.
|
260
|
+
#
|
261
|
+
# The opened File object will be returned. If *read_only* is true, and the file
|
262
|
+
# does not exist, then nil will be returned.
|
263
|
+
#
|
264
|
+
# All exceptions are propagated.
|
265
|
+
#
|
266
|
+
def open_and_lock_file: (untyped filename, untyped read_only) -> untyped
|
267
|
+
|
268
|
+
def save_data: (untyped original_checksum, untyped original_file_size, untyped file) -> untyped
|
269
|
+
|
270
|
+
def save_data_with_atomic_file_rename_strategy: (untyped data, untyped file) -> untyped
|
271
|
+
|
272
|
+
def save_data_with_fast_strategy: (untyped data, untyped file) -> untyped
|
273
|
+
end
|
274
|
+
|
275
|
+
PStore::EMPTY_MARSHAL_CHECKSUM: String
|
276
|
+
|
277
|
+
PStore::EMPTY_MARSHAL_DATA: String
|
278
|
+
|
279
|
+
PStore::EMPTY_STRING: String
|
280
|
+
|
281
|
+
PStore::RDWR_ACCESS: Hash[untyped, untyped]
|
282
|
+
|
283
|
+
PStore::RD_ACCESS: Hash[untyped, untyped]
|
284
|
+
|
285
|
+
PStore::VERSION: String
|
286
|
+
|
287
|
+
PStore::WR_ACCESS: Hash[untyped, untyped]
|