Permalink
Browse files

upgraded Pod to next-gen S26

...essentially this means changing a lot of Pod comments to the '#=[]' form.
Also updated a few cases of stale Pod.
  • Loading branch information...
masak committed Aug 18, 2009
1 parent 0da8964 commit 79bc10ab288e41c5223eaae0a0931d2a0b8c918d
View
@@ -1,21 +1,18 @@
+#= Base class collecting ambient regexes, attributes and methods.
class Druid::Base;
-=begin SUMMARY
-C<Druid::Base> is the base class of most other Druid classes, collecting
-regexes, attributes and methods which most of these other classes need.
-=end SUMMARY
-
# RAKUDO: Cannot use dashes here. [perl #64464]
regex col_letter { <[a..z]> }
regex row_number { \d+ }
regex coords { <col_letter><row_number> }
-our $.sarsen-move = /^ <coords> $/;
-our $.lintel-move = /^ <coords> '-' <coords> $/;
-our $.pass = /^ ['pass' | 'p'] $/;
-our $.swap = /^ ['swap' | 's'] $/;
-our $.resign = /^ ['resign' | 'r'] $/;
+our $.sarsen-move = /^ <coords> $/; #= A sarsen (length 1) move
+our $.lintel-move = /^ <coords> '-' <coords> $/; #= A lintel (length 3) move
+our $.pass = /^ ['pass' | 'p'] $/; #= A passing (no-op) move
+our $.swap = /^ ['swap' | 's'] $/; #= A swap move
+our $.resign = /^ ['resign' | 'r'] $/; #= A forfeit
+#= Returns (zero-based) row and column, given a C<Match> object
method extract-coords(Match $m) {
# RAKUDO: Hoping these explicit int(...) conversions won't be
# necessary in the long run.
View
@@ -3,10 +3,7 @@ use v6;
use Druid::Base;
use Druid::Game::Subject;
-class Druid::Game is Druid::Base does Druid::Game::Subject;
-
-=begin SUMMARY
-An instance of C<Druid::Game> holds an ongoing (or finished) Druid game.
+#=[An instance of C<Druid::Game> holds an ongoing (or finished) Druid game.
It keeps track of the contents of the board, whose turn it is, the number
of moves made, and whether the game is over. The methods in this class
are created so as to disallow all illegal moves (or other actions) on the
@@ -15,22 +12,22 @@ always in a permitted states, according to the rules of Druid.
The class does the role C<Druid::Game::Subject>, making it possible for
instances of other classes to subscribe to updates from instances of this
-class, in an B<observer> pattern.
-=end SUMMARY
+class, in an B<observer> pattern.]
+class Druid::Game is Druid::Base does Druid::Game::Subject;
-=attr The size of a side of the (always quadratic) board.
+#=[ The size of a side of the (always quadratic) board. ]
has $.size;
-=attr An array of layers, each a C<$.size * $.size> AoA with color info.
+#=[ An array of layers, each a C<$.size * $.size> AoA with color info. ]
has @.layers;
-=attr A C<$.size * $.size> AoA with height info.
+#=[ A C<$.size * $.size> AoA with height info. ]
has @.heights;
-=attr A C<$.size * $.size> AoA with color info.
+#=[ A C<$.size * $.size> AoA with color info. ]
has @.colors;
-=attr An integer (either 1 or 2) denoting whose turn it is to move.
+#=[ An integer (either 1 or 2) denoting whose turn it is to move. ]
has $.player-to-move;
-=attr The number of moves made so far in the game, including swapping.
+#=[ The number of moves made so far in the game, including swapping. ]
has $.moves-so-far;
-=attr Whether the game has already ended.
+#=[ Whether the game has already ended. ]
has $.finished;
has $!latest-move;
@@ -46,11 +43,9 @@ submethod BUILD(:$size = 3) {
$!size = $size;
}
-=begin METHOD
-Reports C<False> if the move is permissible in the given state of the game,
-or a C<Str> explaining why if it isn't. (Thus 'bad' here means
-'impermissible', but 'bad' is less to write.)
-=end METHOD
+#=[Reports C<False> if the move is permissible in the given state of
+the game, or a C<Str> explaining why if it isn't. (Thus 'bad' here means
+'impermissible', but 'bad' is less to write.)]
method is-move-bad(Str $move) {
my $color = $!player-to-move;
@@ -92,11 +87,9 @@ something like "b2" or something like "c1-c3" You can also "pass" or
return False; # move is OK
}
-=begin METHOD
-Returns, for given C<$row>, C<$column>, and C<$color>, the reason why
+#=[Returns, for given C<$row>, C<$column>, and C<$color>, the reason why
a sarsen (a one-block piece) of that color cannot be placed on that location,
-or C<False> if the placing of the sarsen is permissible.
-=end METHOD
+or C<False> if the placing of the sarsen is permissible.]
method is-sarsen-move-bad(Int $row, Int $column, Int $color) {
return "The rightmost column is '{chr(ord('A')+$.size-1)}'"
if $column >= $.size;
@@ -111,16 +104,14 @@ method is-sarsen-move-bad(Int $row, Int $column, Int $color) {
return False; # The move is fine.
}
-=begin METHOD
-Returns, for a given C<$row_1>, C<$row_2>, C<$column_1>, C<$column_2>, and
+#=[Returns, for a given C<$row_1>, C<$row_2>, C<$column_1>, C<$column_2>, and
C<$color>, the reason why a lintel (a three-block piece) of that color cannot
be placed bridging these locations, or C<False> if the placing of the lintel
is permissible.
There are no preconditions on the coordinate parameters to be exactly two
rows or two columns apart; instead, these conditions are also tested in this
-method.
-=end METHOD
+method.]
method is-lintel-move-bad(Int $row_1, Int $row_2,
Int $column_1, Int $column_2,
Int $color) {
@@ -164,10 +155,8 @@ method is-lintel-move-bad(Int $row_1, Int $row_2,
return False; # The move is fine.
}
-=begin METHOD
-Analyzes a given move, and makes the appropriate changes to the attributes
-of this C<Druid::Game>. C<fail>s if the move isn't valid.
-=end METHOD
+#=[Analyzes a given move, and makes the appropriate changes to the attributes
+of this C<Druid::Game>. C<fail>s if the move isn't valid.]
method make-move(Str $move) {
fail $reason
@@ -237,10 +226,8 @@ method make-move(Str $move) {
return $move;
}
-=begin METHOD
-Returns a C<Bool> indicating whether the latest move created a winning chain
-across the board.
-=end METHOD
+#=[Returns a C<Bool> indicating whether the latest move created
+a winning chain across the board.]
submethod move-was-winning() {
my ($row, $col) = self.extract-coords(
@@ -309,10 +296,8 @@ submethod move-was-winning() {
return False;
}
-=begin METHOD
-Returns a C<List> of the possible moves in this C<Druid::Game>, represented as
-C<Str>s.
-=end METHOD
+#=[Returns a C<List> of the possible moves in this C<Druid::Game>,
+represented as C<Str>s.]
method possible-moves() {
# We don't handle lintel moves yet. :( I have a nice O(1) algorithm,
# but very little time.
View
@@ -1,27 +1,21 @@
-role Druid::Game::Observer;
-
-=begin SUMMARY
-This role enables objects to I<observe> a C<Druid::Game::Subject>, i.e.
+#=[This role enables objects to I<observe> a C<Druid::Game::Subject>, i.e.
to be notified when that instance changes state in any of various ways.
In concrete terms, an object doing C<Druid::Game::Observer> is added to
a list of observers in a C<Druid::Game::Subject>, which then makes sure
to call the below methods on all observers in that list whenever the
corresponding state change happens in the subject.
Examples of classes which might want to observe a C<Druid::Game::Subject>
-are classes derived from C<Druid::View> or C<Druid::Player>.
-=end SUMMARY
+are classes derived from C<Druid::View> or C<Druid::Player>.]
+role Druid::Game::Observer;
-=begin METHOD
-Gets called any time the C<Druid::Game::Subject> adds a piece to its game
+#=[Gets called any time the C<Druid::Game::Subject> adds a piece to its game
board. Note that, for the purposes of this method, lintels are considered
-to be three adjacent (but separate) pieces.
-=end METHOD
+to be three adjacent (but separate) pieces.]
method add-piece($height, $row, $column, $color) { ... };
-=begin METHOD
-Gets called when the C<Druid::Game::Subject> swaps positions between the
-two players.
+#=[Gets called when the C<Druid::Game::Subject> swaps positions between the
+two players.]
=end METHOD
method swap() { ... }
View
@@ -1,22 +1,22 @@
use v6;
use Druid::Game::Observer;
-role Druid::Game::Subject;
-
-=begin SUMMARY
-This role enables objects to be I<observed> by one or more
-C<Druid::Game::Observer>s, i.e. to be notify these when the object changes
+#=[This role enables objects to be I<observed> by one or more
+C<Druid::Game::Observer>s, i.e. to notify these when the object changes
state in any of various ways. This role only handles the adding of observers;
the actual state change notifications are made by classes doing this role.
Examples of classes which might want to observe a C<Druid::Game::Subject>
-are classes derived from C<Druid::View> or C<Druid::Player>.
-=end SUMMARY
+are classes derived from C<Druid::View> or C<Druid::Player>.]
+role Druid::Game::Subject;
# RAKUDO: Typed arrays don't really work yet
#has Druid::Game::Observer @!observers;
has @!observers;
+#=[Attaches a C<Druid::Game::Observer> to this object. From now on,
+notifications going out to all listening objects will also go out to the
+added C<Druid::Game::Observer>.]
method attach(Druid::Game::Observer $observer) {
unless @!observers ~~ (*, $observer, *) {
@!observers.push($observer);
View
@@ -3,17 +3,14 @@ use v6;
use Druid::Game;
use Druid::Game::Observer;
-class Druid::Player is Druid::Base does Druid::Game::Observer;
-
-=begin SUMMARY
-Represents a generic Druid player. A player belongs to a certain game, has
+#=[Represents a generic Druid player. A player belongs to a certain game, has
a piece color in that game, and is responsible for choosing legal moves
-and making them.
-=end SUMMARY
+and making them.]
+class Druid::Player is Druid::Base does Druid::Game::Observer;
-=attr The game this C<Druid::Player> is playing.
+#=[ The game this C<Druid::Player> is playing. ]
has Druid::Game $!game handles <size layers colors heights make-move>;
-=attr The color of this C<Druid::Player>'s pieces.
+#=[ The color of this C<Druid::Player>'s pieces. ]
has Int $.color where 1|2;
submethod BUILD(Druid::Game :$game!, Int :$color! where { $_ == 1|2 }) {
@@ -2,13 +2,11 @@ use v6;
use Druid::Player;
+#=[ A computer player. It currently tries to move close to its opponent's
+last move or, failing that, entirely randomly. Thus it is almost
+ridiculously easily defeatable.]
class Druid::Player::Computer is Druid::Player;
-=begin SUMMARY
-A computer player. It currently only makes random sarsen moves, and is thus
-ridiculously easily defeatable.
-=end SUMMARY
-
has $!last-move;
method choose-move() {
@@ -1,13 +1,10 @@
use v6;
use Druid::Player;
+#=[A human player, i.e. a C<Druid::Player> whose moves are typed in on C<$*IN>
+by a human.]
class Druid::Player::Human is Druid::Player;
-=begin SUMMARY
-A human player, i.e. a C<Druid::Player> whose moves are typed in on C<$*IN>
-by a human.
-=end SUMMARY
-
method choose-move() {
do Whatever until my $move = self.input-valid-move();
return $move;
View
@@ -3,17 +3,14 @@ use v6;
use Druid::Game;
use Druid::Game::Observer;
+#=[Base class for classes that represent a C<Druid::Game> visually.]
class Druid::View is Druid::Base does Druid::Game::Observer;
-=begin SUMMARY
-Base class for classes that represent a C<Druid::Game> visually.
-=end SUMMARY
-
has Druid::Game $!game handles <size layers colors heights>;
submethod BUILD(Druid::Game :$game!) {
$game.attach(self);
- # RAKUDO: These attributes should be auto-initialized
+ # RAKUDO: This attribute should be auto-initialized
$!game = $game;
}
Oops, something went wrong.

0 comments on commit 79bc10a

Please sign in to comment.