rbs 0.12.1 → 0.15.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ruby.yml +1 -1
  3. data/.gitignore +0 -1
  4. data/CHANGELOG.md +31 -0
  5. data/Gemfile +3 -0
  6. data/README.md +8 -2
  7. data/Rakefile +2 -2
  8. data/Steepfile +1 -0
  9. data/bin/annotate-with-rdoc +1 -1
  10. data/bin/setup +0 -2
  11. data/docs/CONTRIBUTING.md +1 -0
  12. data/docs/syntax.md +50 -6
  13. data/goodcheck.yml +22 -5
  14. data/lib/rbs/ast/comment.rb +1 -1
  15. data/lib/rbs/cli.rb +12 -4
  16. data/lib/rbs/constant.rb +1 -1
  17. data/lib/rbs/constant_table.rb +9 -8
  18. data/lib/rbs/definition_builder.rb +6 -7
  19. data/lib/rbs/environment.rb +5 -1
  20. data/lib/rbs/environment_loader.rb +12 -12
  21. data/lib/rbs/namespace.rb +1 -1
  22. data/lib/rbs/parser.rb +3148 -0
  23. data/lib/rbs/parser.y +10 -3
  24. data/lib/rbs/prototype/rb.rb +38 -6
  25. data/lib/rbs/prototype/runtime.rb +17 -7
  26. data/lib/rbs/test/hook.rb +2 -0
  27. data/lib/rbs/test/setup_helper.rb +4 -4
  28. data/lib/rbs/test/tester.rb +4 -1
  29. data/lib/rbs/test/type_check.rb +12 -6
  30. data/lib/rbs/type_name.rb +1 -1
  31. data/lib/rbs/variance_calculator.rb +2 -2
  32. data/lib/rbs/version.rb +1 -1
  33. data/lib/rbs/writer.rb +25 -15
  34. data/sig/constant.rbs +21 -0
  35. data/sig/constant_table.rbs +30 -0
  36. data/sig/declarations.rbs +2 -2
  37. data/sig/definition.rbs +2 -2
  38. data/sig/definition_builder.rbs +4 -5
  39. data/sig/environment_loader.rbs +54 -0
  40. data/sig/members.rbs +2 -2
  41. data/sig/method_types.rbs +1 -1
  42. data/sig/namespace.rbs +4 -4
  43. data/sig/parser.rbs +25 -0
  44. data/sig/substitution.rbs +3 -3
  45. data/sig/typename.rbs +1 -1
  46. data/sig/types.rbs +1 -1
  47. data/sig/version.rbs +3 -0
  48. data/sig/writer.rbs +40 -0
  49. data/stdlib/base64/base64.rbs +1 -1
  50. data/stdlib/benchmark/benchmark.rbs +2 -2
  51. data/stdlib/builtin/array.rbs +124 -120
  52. data/stdlib/builtin/basic_object.rbs +54 -54
  53. data/stdlib/builtin/binding.rbs +42 -42
  54. data/stdlib/builtin/builtin.rbs +28 -0
  55. data/stdlib/builtin/class.rbs +33 -33
  56. data/stdlib/builtin/complex.rbs +90 -90
  57. data/stdlib/builtin/encoding.rbs +33 -33
  58. data/stdlib/builtin/enumerable.rbs +58 -52
  59. data/stdlib/builtin/enumerator.rbs +35 -35
  60. data/stdlib/builtin/errors.rbs +2 -2
  61. data/stdlib/builtin/exception.rbs +50 -50
  62. data/stdlib/builtin/false_class.rbs +6 -6
  63. data/stdlib/builtin/fiber.rbs +14 -14
  64. data/stdlib/builtin/fiber_error.rbs +1 -1
  65. data/stdlib/builtin/float.rbs +161 -161
  66. data/stdlib/builtin/gc.rbs +3 -3
  67. data/stdlib/builtin/hash.rbs +7 -7
  68. data/stdlib/builtin/io.rbs +88 -88
  69. data/stdlib/builtin/kernel.rbs +71 -153
  70. data/stdlib/builtin/match_data.rbs +1 -1
  71. data/stdlib/builtin/method.rbs +19 -19
  72. data/stdlib/builtin/module.rbs +13 -13
  73. data/stdlib/builtin/nil_class.rbs +20 -20
  74. data/stdlib/builtin/numeric.rbs +101 -101
  75. data/stdlib/builtin/object.rbs +173 -173
  76. data/stdlib/builtin/proc.rbs +91 -91
  77. data/stdlib/builtin/random.rbs +1 -1
  78. data/stdlib/builtin/range.rbs +3 -5
  79. data/stdlib/builtin/rational.rbs +83 -83
  80. data/stdlib/builtin/signal.rbs +7 -7
  81. data/stdlib/builtin/string.rbs +10 -10
  82. data/stdlib/builtin/string_io.rbs +8 -8
  83. data/stdlib/builtin/struct.rbs +1 -1
  84. data/stdlib/builtin/symbol.rbs +1 -1
  85. data/stdlib/builtin/thread.rbs +189 -189
  86. data/stdlib/builtin/thread_group.rbs +2 -2
  87. data/stdlib/builtin/true_class.rbs +10 -10
  88. data/stdlib/builtin/warning.rbs +1 -1
  89. data/stdlib/coverage/coverage.rbs +2 -2
  90. data/stdlib/csv/csv.rbs +1 -1
  91. data/stdlib/date/date.rbs +4 -4
  92. data/stdlib/date/date_time.rbs +1 -1
  93. data/stdlib/find/find.rbs +12 -12
  94. data/stdlib/logger/log_device.rbs +1 -1
  95. data/stdlib/logger/logger.rbs +1 -1
  96. data/stdlib/pathname/pathname.rbs +41 -39
  97. data/stdlib/pstore/pstore.rbs +287 -0
  98. data/stdlib/pty/pty.rbs +5 -29
  99. data/stdlib/tmpdir/tmpdir.rbs +12 -12
  100. data/stdlib/uri/generic.rbs +2 -2
  101. data/stdlib/uri/http.rbs +158 -0
  102. data/stdlib/uri/https.rbs +108 -0
  103. data/stdlib/uri/ldap.rbs +224 -0
  104. data/stdlib/uri/ldaps.rbs +108 -0
  105. data/steep/Gemfile.lock +13 -17
  106. 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 |: (bool obj) -> bool
44
+ #
45
+ def |: (boolish obj) -> bool
46
46
  end
@@ -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: bool, ?clear: bool) -> Hash[String, untyped]
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: bool, ?branches: bool, ?methods: bool, ?oneshot_lines: bool) -> nil
61
+ def self.start: (?lines: boolish, ?branches: boolish, ?methods: boolish, ?oneshot_lines: boolish) -> nil
62
62
  end
@@ -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: bool, **untyped) -> untyped
758
+ def to_csv: (?write_headers: boolish, **untyped) -> untyped
759
759
 
760
760
  alias to_s to_csv
761
761
 
@@ -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, ?bool complete) -> Hash[Symbol, Integer]
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, ?bool complete, ?Integer start) -> Date
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.
@@ -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, ?bool complete, ?Integer start) -> DateTime
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.
@@ -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: bool) -> Enumerator[String, nil]
31
- | (*String | _ToPath paths, ?ignore_error: bool) { (String arg0) -> void } -> nil
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: bool, ?shift_period_suffix: String, ?shift_size: Integer, ?shift_age: Numeric | String) -> void
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
 
@@ -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: bool, ?datetime_format: String, ?formatter: _Formatter, ?progname: String, ?level: Integer) -> void
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: bool,
328
- ?binmode: bool,
329
- ?autoclose: bool,
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: (?bool with_directory) -> untyped
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: (?bool consider_symlink) -> Pathname
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: (?bool with_directory) { (Pathname) -> void } -> Array[Pathname]
489
- | (?bool with_directory) -> Enumerator[Pathname, Array[Pathname]]
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: bool,
521
- ?binmode: bool,
522
- ?autoclose: bool,
520
+ ?textmode: boolish,
521
+ ?binmode: boolish,
522
+ ?autoclose: boolish,
523
523
  # getline_args
524
- ?chomp: bool,
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: bool,
534
- ?binmode: bool,
535
- ?autoclose: bool,
533
+ ?textmode: boolish,
534
+ ?binmode: boolish,
535
+ ?autoclose: boolish,
536
536
  # getline_args
537
- ?chomp: bool,
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: bool,
547
- ?binmode: bool,
548
- ?autoclose: bool,
546
+ ?textmode: boolish,
547
+ ?binmode: boolish,
548
+ ?autoclose: boolish,
549
549
  # getline_args
550
- ?chomp: bool,
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: bool,
560
- ?binmode: bool,
561
- ?autoclose: bool,
559
+ ?textmode: boolish,
560
+ ?binmode: boolish,
561
+ ?autoclose: boolish,
562
562
  # getline_args
563
- ?chomp: bool,
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: bool) { (Pathname) -> untyped } -> nil
647
- | (?ignore_error: bool) -> Enumerator[Pathname, nil]
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: bool,
793
- ?binmode: bool,
794
- ?autoclose: bool,
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: bool,
817
- ?binmode: bool,
818
- ?autoclose: bool,
816
+ ?textmode: boolish,
817
+ ?binmode: boolish,
818
+ ?autoclose: boolish,
819
819
  # getline_args
820
- ?chomp: bool,
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: bool,
830
- ?binmode: bool,
831
- ?autoclose: bool,
829
+ ?textmode: boolish,
830
+ ?binmode: boolish,
831
+ ?autoclose: boolish,
832
832
  # getline_args
833
- ?chomp: bool,
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: bool,
1037
- ?binmode: bool,
1038
- ?autoclose: bool,
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]