Create program structure UML diagram

[lucubrator]

Link to UML document: https://drive.google.com/file/d/1gY7VBtIZeASWFPCIylkw11IkiXyLN8rt/view?usp=sharing

[lucubrator]

TODO: Would be nice if the figure had a little bit of a white margin around the diagram elements.

[lucubrator]

Switched names of struct fields to snake case according to the Rust Style Guide.

An updated figure needs to be generated and put into README.md. This can probably wait a bit though, more changes are probably coming soon.

[lucubrator]

Update structure UML diagram from 0.1.0 -> 1.0.2

Summary

• Extensive update to structure diagram (hence updating the major version number)
• UML arrows, elements and naming now according to UML standards
• Switched from Classes and inheritance model to Rusts Structs and Traits model
• Implementations:
  • Target and Pile traits
  • Divided Piles-struct into Deck, Stack and Exile structs which implements the Pile trait
  • Hand and ManaTokenPool structs
  • Effect and TargetType enums
  • Various methods

Note: incorrectly says "Effect and TargetType structs" instead of "enums" in the commit message.

TODO: Would be nice if the figure had a little bit of a white margin around the diagram elements.

Fixed.

Changes to methods

draw(num: usize): Result<Vec<Card>, E>

This method is implemented with the Pile trait and can also be used in the following way to specify drawing from top or bottom:

draw(num: usize).from(source: String): Result<Card, E>

Allowed values for source: String are:

• "Top" : Draw from the top of the Pile.
• "Bottom" : Draw from the bottom of the Pile.
• "Random" : Draw randomly from the Pile.

Top draw is default, so: draw(3) is identical to draw(3).from("Top")   

update_target_status(): Result<T, E>

Method of objects with the Target trait. Updates the target_types: Vec<TargetType> field of the object according to the player who has focus (see also: the Game.focused_player field). The TargetType enum has the following enum values (prob. more to come):

• Self
• Player
• Opponent
• Card

Example: Player-objects have the Target trait and hence a target_type: TargetType field. Let's say we have a Player-object, player1. Currently, it is not player1's turn (since Game.current_player != *player1) but it is however player1's turn to respond to something his opponent has done, i.e. player1 has the "focus" (represented by Game.focused_player == *player1).

Hence, currently, player1.target_type == vec![Player, Self]. When player1 acts and passes focus to his opponent, player1.update_target_status() is called, changing player1.target_type to vec![Player, Opponent].   

discard(cards: Vec<Card>): Result<T, E>

The discard(cards) method of the Stack struct shuffles and moves the selected cards from the stack to the Deck. The method can also be used in the following way:

discard().shuffle(bool).all(): Result<T, E>

Calling discard().shuffle(false).all() simply moves all cards in the current Stack to the Deck. Calling discard().shuffle(true).all() first calles self.shuffle() and then moves all cards to the Deck. Shuffling before returning the cards to the deck is the default behavior. The method-chained .all() is optionary.   

[lucubrator]

Update structure UML diagram from 1.0.2 -> 1.1.0

Link to UML document: https://drive.google.com/file/d/1gY7VBtIZeASWFPCIylkw11IkiXyLN8rt/view?usp=sharing

Summary

• Add Board and CardPosition structs
• Add CanDiscard trait
• Add PositionType enum
• Add and update various methods
• Improve element and arrow positioning on diagram

Changes to methods

change_position(new_position: PositionType, [coords: (isize, isize)]): Result<T, E>

Modifies the position of a card. Is a method of the CardPosition struct (context: each Card object has a position: CardPosition field).

The new_position: PositionType argument takes in a any of the PositionType enum values:

• Deck
• Hand
• Board
• Stack
• Exile

The coords: (x: isize, y: size) argument should (and must) only be supplied when new_position == Board and represents the card's position on the board.

@NAIBAFFF: Perhaps the sign of the y-coord can represent on which side of the board the card is located?
  

_update_card_positions(Vec<Card>): Result<T, E>

Is an internal method of all Zone objects (objects which holds cards, e.g. Pile, Board and Hand objects). Corrects the position of all contained Card objects. Is automatically called when the Zone object's state has changed in a significant way (e.g. when cards have been added or moved).

Example:

Let's say we have a Hand object called player1_hand. During a game tick, a Card, let's call it card1, is moved from the deck and added to player1_hand through the calls:

let card1 = deck.draw(1).unwrap().nth(0)
player1_hand.add(Vec![card1])

Internally to the add() method of player1_hand, _update_card_positions() is then called on the all changing cards (a Vec<Card>; in this case containing only card1). Finally, within _update_card_positions(), change_position() is called on each card:

// Inside add(cards)
let new_position: PositionType = Hand  // enum value depends on the Zone in to which (or within) the card moves
for card in cards {
    card.CardPosition.change_position(new_position)
}

[lucubrator]

The diagram has grown and would need some care.

TODO(need help!): Tidy up/restructure/optimize UML element positions to reduce crossing arrows etc.

[lucubrator]

Restructuring

Link to current UML document: https://drive.google.com/file/d/1gY7VBtIZeASWFPCIylkw11IkiXyLN8rt/view?usp=sharing

See discussion below:

Measures

• Update according to the discussion above.
• Remove exile(), add(), and return() methods.
• Change draw methods.
• Add back Stack struct but with field cards: indexmap::map::IndexMap<Card> with new method resolve_stack(): Result<T, E>.
• Add backups of the different versions of the UML diagram to repo (see commit beaffeb0).