Class: PortableMoveNotation::Action

Inherits:
Object
  • Object
show all
Defined in:
lib/portable_move_notation/action.rb

Overview

Action

An Action is the atomic unit of Portable Move Notation. Each instance describes one deterministic transformation applied to either the board or the mover’s reserve using the PMN v1.0.0 array format.

PMN v1.0.0 uses a 4-element array format: ‘[source_square, destination_square, piece_name, captured_piece]`

| Index | Field | Type | Meaning | |——-|——————|—————-|————————————————————| | 0 | ‘src_square` | String or nil | Square vacated (nil when dropping from hand) | | 1 | `dst_square` | String | Square now occupied by piece_name | | 2 | `piece_name` | String | Post-action piece identifier (may contain modifiers) | | 3 | `captured_piece` | String or nil | Piece entering mover’s reserve (nil if nothing captured) |

The implicit side‑effects are rule‑agnostic:

  • ‘src_square` (when not nil) becomes empty.

  • ‘dst_square` now contains `piece_name`.

  • If ‘captured_piece` is set, add exactly one such piece to the mover’s reserve.

  • If ‘src_square` is nil, remove one copy of `piece_name` from hand.

Examples

Examples:

Basic piece movement (Chess pawn e2 → e4)

PortableMoveNotation::Action.new("e2", "e4", "P", nil)

Drop from hand (Shogi pawn onto 27)

PortableMoveNotation::Action.new(nil, "27", "p", nil)

Capture with promotion (Bishop captures +p, promotes, P enters hand)

PortableMoveNotation::Action.new("36", "27", "+B", "P")

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(src_square, dst_square, piece_name, captured_piece) ⇒ Action

Instantiates a new PortableMoveNotation::Action using PMN v1.0.0 array semantics.

Parameters:

  • src_square (String, nil) —

    Source coordinate or nil for drops.

  • dst_square (String) —

    Destination coordinate (required).

  • piece_name (String) —

    Post‑action piece identifier (required).

  • captured_piece (String, nil) —

    Captured piece entering hand.

Raises:

  • (ArgumentError) —

    If any value fails validation.



105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/portable_move_notation/action.rb', line 105

def initialize(src_square, dst_square, piece_name, captured_piece)
  validate_square(src_square) unless src_square.nil?
  validate_square(dst_square)
  validate_piece_name(piece_name)
  validate_captured_piece(captured_piece) unless captured_piece.nil?

  @src_square = src_square
  @dst_square = dst_square
  @piece_name = piece_name
  @captured_piece = captured_piece

  freeze
end

Instance Attribute Details

#captured_piece ⇒ String? (readonly)

Returns Captured piece that enters hand, or nil.

Returns:

  • (String, nil) —

    Captured piece that enters hand, or nil



92
93
94
 
# File 'lib/portable_move_notation/action.rb', line 92

def captured_piece
  @captured_piece
end

#dst_square ⇒ String (readonly)

Returns Destination square.

Returns:

  • (String) —

    Destination square



88
89
90
 
# File 'lib/portable_move_notation/action.rb', line 88

def dst_square
  @dst_square
end

#piece_name ⇒ String (readonly)

Returns Post‑action piece identifier.

Returns:

  • (String) —

    Post‑action piece identifier



90
91
92
 
# File 'lib/portable_move_notation/action.rb', line 90

def piece_name
  @piece_name
end

#src_square ⇒ String? (readonly)

Returns Source square (or nil for drops).

Returns:

  • (String, nil) —

    Source square (or nil for drops)



86
87
88
 
# File 'lib/portable_move_notation/action.rb', line 86

def src_square
  @src_square
end

Class Method Details

.from_array(action_array) ⇒ Action

Builds an PortableMoveNotation::Action from an array following PMN v1.0.0 format.

Parameters:

  • action_array (Array) —

    4-element array [src_square, dst_square, piece_name, captured_piece]

Returns:

Raises:

  • (ArgumentError) —

    If array format is invalid.



74
75
76
77
78
79
 
# File 'lib/portable_move_notation/action.rb', line 74

def self.from_array(action_array)
  raise ArgumentError, "Expected 4-element array" unless action_array.is_a?(::Array) && action_array.size == 4

  src_square, dst_square, piece_name, captured_piece = action_array
  new(src_square, dst_square, piece_name, captured_piece)
end

.valid?(action_data) ⇒ Boolean

Validates that action_data is a structurally correct PMN **action array**. Expects a 4-element array following the PMN v1.0.0 format.

Parameters:

  • action_data (Array) —

    Raw PMN action array.

Returns:



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/portable_move_notation/action.rb', line 48

def self.valid?(action_data)
  return false unless action_data.is_a?(::Array)
  return false unless action_data.size == 4

  src_square, dst_square, piece_name, captured_piece = action_data

  # Validate dst_square and piece_name are non-empty strings
  return false unless dst_square.is_a?(::String) && !dst_square.empty?
  return false unless piece_name.is_a?(::String) && !piece_name.empty?

  # Validate src_square is either nil or non-empty string
  return false unless src_square.nil? || (src_square.is_a?(::String) && !src_square.empty?)

  # Validate captured_piece is either nil or non-empty string
  return false unless captured_piece.nil? || (captured_piece.is_a?(::String) && !captured_piece.empty?)

  true
rescue StandardError
  false
end

Instance Method Details

#==(other) ⇒ Object

Compare actions based on their array representation



139
140
141
 
# File 'lib/portable_move_notation/action.rb', line 139

def ==(other)
  other.is_a?(Action) && to_a == other.to_a
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


148
149
150
 
# File 'lib/portable_move_notation/action.rb', line 148

def eql?(other)
  self == other
end

#hash ⇒ Object

Hash based on array representation



144
145
146
 
# File 'lib/portable_move_notation/action.rb', line 144

def hash
  to_a.hash
end

#inspect ⇒ Object

Human-readable string representation



153
154
155
 
# File 'lib/portable_move_notation/action.rb', line 153

def inspect
  "#<#{self.class.name} #{to_a.inspect}>"
end

#to_a ⇒ Array Also known as: to_pmn

Returns the PMN v1.0.0 array representation. This is the canonical format for JSON serialization.

Returns:

  • (Array) —

    4-element array [src_square, dst_square, piece_name, captured_piece]



127
128
129
 
# File 'lib/portable_move_notation/action.rb', line 127

def to_a
  [src_square, dst_square, piece_name, captured_piece]
end

#to_s ⇒ Object 



157
158
159
 
# File 'lib/portable_move_notation/action.rb', line 157

def to_s
  to_a.to_s
end