Module: Docscribe::Infer::Params

Defined in:
lib/docscribe/infer/params.rb

Overview

Parameter type inference.

Class Method Summary collapse

Class Method Details

.infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true) ⇒ String

Note:

module_function: when included, also defines #infer_param_type (instance visibility: private)

Infer a parameter type from an internal parameter name representation and an optional default expression.

Handles:

  • positional/rest/block parameter prefixes (‘*`, `**`, `&`)

  • keyword params with and without defaults

  • special-casing ‘options:` as `Hash` when enabled

  • literal defaults via AST parsing

Parameters:

  • name (String) —

    parameter name as used internally (may include ‘*`, `**`, `&`, or trailing `:`)

  • default_str (String, nil) —

    source for the default value expression

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    type returned when inference is uncertain

  • treat_options_keyword_as_hash (Boolean) (defaults to: true) —

    whether ‘options:` should be treated specially as Hash

Returns:

  • (String) 


25
26
27
28
 
# File 'lib/docscribe/infer/params.rb', line 25

def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
  prefix_param_type(name) || inferred_param_type(name, default_str, fallback_type,
                                                 treat_options_keyword_as_hash: treat_options_keyword_as_hash)
end

.inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:) ⇒ String

Note:

module_function: when included, also defines # (instance visibility: private)

Infer type for a regular or keyword parameter with optional default.

Parameters:

  • name (String) —

    parameter name

  • default_str (String, nil) —

    default expression source

  • fallback_type (String)
  • treat_options_keyword_as_hash (Boolean)

Returns:

  • (String) 


53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/docscribe/infer/params.rb', line 53

def inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:)
  if name.end_with?(':') && default_str.nil?
    return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
  end

  node = parse_expr(default_str)
  ty = Literals.type_from_literal(node, fallback_type: fallback_type)

  return 'Hash' if options_hash_keyword?(name, default_str, ty, treat_options_keyword_as_hash)

  ty
end

.options_hash_keyword?(name, default_str, type, treat_options_keyword_as_hash) ⇒ Boolean

Note:

module_function: when included, also defines #options_hash_keyword? (instance visibility: private)

Whether a keyword parameter named ‘options:’ with a hash default should be typed as Hash.

Parameters:

  • name (String) —

    parameter name

  • default_str (String, nil) —

    default expression source

  • type (String) —

    inferred type

  • treat_options_keyword_as_hash (Boolean) —

    whether to treat ‘options:’ as Hash

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/docscribe/infer/params.rb', line 85

def options_hash_keyword?(name, default_str, type, treat_options_keyword_as_hash)
  treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || type == 'Hash')
end

.options_keyword_type(name, treat_options_keyword_as_hash, fallback_type) ⇒ String

Note:

module_function: when included, also defines #options_keyword_type (instance visibility: private)

Return ‘Hash’ for a keyword parameter named ‘options:’ when special-cased, else fallback.

Parameters:

  • name (String) —

    parameter name

  • treat_options_keyword_as_hash (Boolean) —

    whether to treat ‘options:’ as Hash

  • fallback_type (String) —

    type returned when not special-cased

Returns:

  • (String) 


73
74
75
 
# File 'lib/docscribe/infer/params.rb', line 73

def options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
  treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type
end

.parse_expr(src) ⇒ Parser::AST::Node?

Note:

module_function: when included, also defines #parse_expr (instance visibility: private)

Parse a standalone expression for parameter-default inference.

Returns nil if the expression is empty or cannot be parsed.

Parameters:

  • src (String, nil) —

    expression source

Returns:

  • (Parser::AST::Node, nil)

Raises:

  • (Parser::SyntaxError) 


97
98
99
100
101
102
103
104
105
 
# File 'lib/docscribe/infer/params.rb', line 97

def parse_expr(src)
  return nil if src.nil? || src.strip.empty?

  buffer = Parser::Source::Buffer.new('(param)')
  buffer.source = src
  Docscribe::Parsing.parse_buffer(buffer)
rescue Parser::SyntaxError
  nil
end

.prefix_param_type(name) ⇒ String?

Note:

module_function: when included, also defines # (instance visibility: private)

Return type for special parameter prefixes.

Parameters:

  • name (String) —

    parameter name

Returns:

  • (String, nil) 


36
37
38
39
40
41
42
 
# File 'lib/docscribe/infer/params.rb', line 36

def prefix_param_type(name)
  return 'Array' if name.start_with?('*') && !name.start_with?('**')
  return 'Hash'  if name.start_with?('**')
  return 'Proc'  if name.start_with?('&')

  nil
end