diff options
author | Kevin Newton <kddnewton@gmail.com> | 2023-10-30 15:11:24 -0400 |
---|---|---|
committer | Kevin Newton <kddnewton@gmail.com> | 2023-11-01 13:10:29 -0400 |
commit | 4490979615338ea21619c2f1287759172c9a2437 (patch) | |
tree | 542d1941faee46e2652f9e78648bfa0e04d52fd9 | |
parent | 79034fbd503769ed2742003e31920733e9300909 (diff) |
[ruby/prism] Finish Ruby documentation
https://github.com/ruby/prism/commit/dfdcc98a3c
-rw-r--r-- | lib/prism/pack.rb | 42 | ||||
-rw-r--r-- | prism/api_pack.c | 29 |
2 files changed, 59 insertions, 12 deletions
diff --git a/lib/prism/pack.rb b/lib/prism/pack.rb index 1b63d02f24..00caf553c6 100644 --- a/lib/prism/pack.rb +++ b/lib/prism/pack.rb @@ -57,8 +57,34 @@ module Prism # A directive in the pack template language. class Directive - attr_reader :version, :variant, :source, :type, :signed, :endian, :size, :length_type, :length + # A symbol representing the version of Ruby. + attr_reader :version + # A symbol representing whether or not we are packing or unpacking. + attr_reader :variant + + # A byteslice of the source string that this directive represents. + attr_reader :source + + # The type of the directive. + attr_reader :type + + # The type of signedness of the directive. + attr_reader :signed + + # The type of endianness of the directive. + attr_reader :endian + + # The size of the directive. + attr_reader :size + + # The length type of this directive (used for integers). + attr_reader :length_type + + # The length of this directive (used for integers). + attr_reader :length + + # Initialize a new directive with the given values. def initialize(version, variant, source, type, signed, endian, size, length_type, length) @version = version @variant = variant @@ -71,6 +97,7 @@ module Prism @length = length end + # The descriptions of the various types of endianness. ENDIAN_DESCRIPTIONS = { AGNOSTIC_ENDIAN: "agnostic", LITTLE_ENDIAN: "little-endian (VAX)", @@ -79,12 +106,14 @@ module Prism ENDIAN_NA: "n/a" } + # The descriptions of the various types of signedness. SIGNED_DESCRIPTIONS = { UNSIGNED: "unsigned", SIGNED: "signed", SIGNED_NA: "n/a" } + # The descriptions of the various types of sizes. SIZE_DESCRIPTIONS = { SIZE_SHORT: "short", SIZE_INT: "int-width", @@ -97,6 +126,7 @@ module Prism SIZE_P: "pointer-width" } + # Provide a human-readable description of the directive. def describe case type when SPACE @@ -161,15 +191,21 @@ module Prism end end - # A class used to describe what a pack template does. + # The result of parsing a pack template. class Format - attr_reader :directives, :encoding + # A list of the directives in the template. + attr_reader :directives + + # The encoding of the template. + attr_reader :encoding + # Create a new Format with the given directives and encoding. def initialize(directives, encoding) @directives = directives @encoding = encoding end + # Provide a human-readable description of the format. def describe source_width = directives.map { |d| d.source.inspect.length }.max directive_lines = directives.map do |directive| diff --git a/prism/api_pack.c b/prism/api_pack.c index bb2f4ea215..c746a59634 100644 --- a/prism/api_pack.c +++ b/prism/api_pack.c @@ -164,6 +164,12 @@ pack_encoding_to_ruby(pm_pack_encoding encoding) { return rb_enc_from_encoding(rb_enc_from_index(index)); } +/** + * call-seq: + * Pack::parse(version, variant, source) -> Format + * + * Parse the given source and return a format object. + */ static VALUE pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_string) { if (version_symbol != v3_2_0_symbol) { @@ -223,15 +229,17 @@ pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_ break; } - VALUE directive_args[9] = { version_symbol, - variant_symbol, - rb_usascii_str_new(directive_start, directive_end - directive_start), - pack_type_to_symbol(type), - pack_signed_to_symbol(signed_type), - pack_endian_to_symbol(endian), - pack_size_to_symbol(size), - pack_length_type_to_symbol(length_type), - UINT64T2NUM(length) }; + VALUE directive_args[9] = { + version_symbol, + variant_symbol, + rb_usascii_str_new(directive_start, directive_end - directive_start), + pack_type_to_symbol(type), + pack_signed_to_symbol(signed_type), + pack_endian_to_symbol(endian), + pack_size_to_symbol(size), + pack_length_type_to_symbol(length_type), + UINT64T2NUM(length) + }; rb_ary_push(directives_array, rb_class_new_instance(9, directive_args, rb_cPrismPackDirective)); } @@ -242,6 +250,9 @@ pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_ return rb_class_new_instance(2, format_args, rb_cPrismPackFormat); } +/** + * The function that gets called when Ruby initializes the prism extension. + */ void Init_prism_pack(void) { rb_cPrism = rb_define_module("Prism"); |