R/lang_wrappers_en.R

In mpru/karel: Learning programming with Karel the robot

# This file contains functions named in English which are just wrappers to the
# internal functions which are agnostic of language. Here I also include the
# documentation in English. Only external functions that can be used by users
# are documented.

# ------------------------------------------------------------------------------

#' Create Karel's world
#'
#' This function takes a "world" (i.e. a list with data about its size, walls,
#' beepers and Karel's position and direction), plots it and prepares everything
#' so that Karel can start performing actions in it. It must be run always
#' before Karel starts working on her goals, especially if we have made a
#' mistake, we must start all over again by first running this function.
#'
#' After running \code{generate_world()}, we can run Karel's actions and finally
#' visualize it all with the function \code{run_actions()}.
#'
#' @param world Character vector of length 1 with the name of one of the
#'   provided worlds in the package or a list provided by the user with all the
#'   components that a world needs (see more below in details).
#'
#' @return Plots the initial state of Karel's world and prepares everything to
#'   start recording her actions.
#'
#' @export
#'
#' @examples
#' generate_world("mundo001")
#'
#' @seealso \code{\link{actions}} \code{\link{run_actions}}
#'
#' @details Argument \code{world} can be create by the user. In this case, it
#'   must be a list with the following components:
#'
#'   \enumerate{
#'     \item \code{nx}: size of Karel's world, number of cells in x-axis.
#'     \item \code{ny}: size of Karel's world, number of cells in y-axis.
#'     \item \code{hor_walls}: a data.frame with a row for each horizontal wall
#'     in Karel's world and 3 columns: x (coordinate of the start of the wall in
#'     the x axis), y (coordinate of the start of the wall in the y axis), lgth
#'     (length of the wall, in number of cells it covers). If it is NULL, there
#'     are no horizontal walls in the world.
#'     \item \code{ver_walls}: a data.frame with a row for each vertical wall in
#'     Karel's world and 3 columns: x (coordinate of the start of the wall in
#'     the x axis), y (coordinate of the start of the wall in the y axis), lgth
#'     (length of the wall, in number of cells it covers). If it takes the value
#'     NULL, there are no vertical walls in the world.
#'     \item \code{karel_x}: x-coordinate for Karel's initial position.
#'     \item \code{karel_y}: y-coordinate for Karel's initial position.
#'     \item \code{karel_dir}: Karel's starting direction: 1 (facing west), 2
#'     (facing north), 3 (facing west), or 4 (facing south).
#'     \item \code{beepers_x}: Numeric vector with the x-axis coordinates of the
#'     cells where there are beepers initially. The length of the vectors
#'     beepers_x, beepers_y and beepers_n must match. If you don't want beepers
#'     in the world, supply the value NULL.
#'     \item \code{beepers_y}: Numeric vector with the coordinates in the y-axis
#'     of the cells where there are beepers initially. The length of the vectors
#'     beepers_x, beepers_y and beepers_n must match. If you don't want beepers
#'     in the world, supply the value NULL.
#'     \item \code{beepers_n}: numeric vector with the number of beepers that
#'     are initially in each of the positions determined by the values of
#'     beepers_x and beepers_y. The length of the vectors beepers_x, beepers_y
#'     and beepers_n must match. If you don't want beepers in the world, supply
#'     the value NULL.
#'     \item \code{beepers_bag}: number of beepers that Karel has available in
#'     its bag at the beginning. Karel can put beepers if it has beepers in its
#'     bag. It can take the value Inf.
#'   }
#'
generate_world <- function(world) .generate_world(world, lang = "en")

# ------------------------------------------------------------------------------

#' Run actions
#'
#' This function produces the animation that shows all actions performed by
#' Karel since its world was generated by \code{generate_world}.
#'
#' @param loop A logical value TRUE or FALSE indicating if the animation should
#' repeat itself after finished or not (defaults to FALSE).
#'
#' @return Produces an animation with \code{gganimate}.
#'
#' @examples
#' generate_world("mundo001")
#' move()
#' pick_beeper()
#' turn_left()
#' put_beeper()
#' if (interactive()) run_actions()
#'
#' @seealso \code{\link{generate_world}}
#'
#' @export
#'
run_actions <- function(loop = FALSE) .run_actions(loop = loop, lang = "en")

# ------------------------------------------------------------------------------

#' Available actions for Karel
#'
#' \code{move()}, \code{turn_left()}, \code{pick_beeper()} y \code{put_beeper()}
#' are the four basic activities that Karel can perform. If you turn on Karel's
#' superpowers with \code{load_super_karel()}, then she can also
#' \code{turn_right()} y \code{turn_around()}.
#'
#' @return These functions don't return anything, but make changes in Karel's
#'   world that are visible when all the actions are run through
#'   \code{run_actions()}.
#'
#' @examples
#' generate_world("mundo001")
#' move()
#' pick_beeper()
#' turn_left()
#' put_beeper()
#' if (interactive()) run_actions()
#'
#' @seealso \code{\link{load_super_karel}} \code{\link{generate_world}}
#'   \code{\link{run_actions}}
#'
#' @name actions
NULL
#> NULL

#' @rdname actions
#' @export
move <- function() .move(lang = "en")

#' @rdname actions
#' @export
turn_left <- function() .turn_left(lang = "en")

#' @rdname actions
#' @export
put_beeper <- function() .put_beeper(lang = "en")

#' @rdname actions
#' @export
pick_beeper <- function() .pick_beeper(lang = "en")

# ------------------------------------------------------------------------------

#' Conditions that Karel can test
#'
#' These group of functions return a logical value \code{TRUE} or \code{FALSE}
#' according to Karel's evaluation of her world.
#'
#' @return Logical value TRUE or FALSE.
#'
#' @details The functions \code{front_is_clear()}, \code{front_is_blocked()},
#'   \code{left_is_clear()}, \code{left_is_blocked()}, \code{right_is_clear()} y
#'   \code{right_is_blocked()} test if there is a wall in front of Karel, to her
#'   left or to her right, respectively. The functions \code{beepers_present()}
#'   and \code{no_beepers_present()} test whether there are any
#'   \code{beepers} at Karel's current position. The functions
#'   \code{karel_has_beepers()} and \code{karel_has_no_beepers()} test if Karel
#'   has any \code{beepers} in her bag (not visible in the plot). The
#'   functions \code{facing_east()}, \code{facing_west()}, \code{facing_north()}
#'   and \code{facing_south()} test the direction to which Karel is facing right
#'   now.
#'
#' @examples
#' generate_world("mundo001")
#' front_is_clear()
#' front_is_blocked()
#' left_is_clear()
#' left_is_blocked()
#' right_is_clear()
#' right_is_blocked()
#' beepers_present()
#' no_beepers_present()
#' karel_has_beepers()
#' karel_has_no_beepers()
#' facing_east()
#' facing_west()
#' facing_north()
#' facing_south()
#'
#' @seealso \code{\link{generate_world}}
#'
#' @name conditions
NULL
#> NULL

#' @rdname conditions
#' @export
front_is_clear <- function() .front_is_clear()

#' @rdname conditions
#' @export
front_is_blocked <- function() .front_is_blocked()

#' @rdname conditions
#' @export
left_is_clear <- function() .left_is_clear()

#' @rdname conditions
#' @export
left_is_blocked <- function() .left_is_blocked()

#' @rdname conditions
#' @export
right_is_clear <- function() .right_is_clear()

#' @rdname conditions
#' @export
right_is_blocked <- function() .right_is_blocked()

#' @rdname conditions
#' @export
beepers_present <- function() .beepers_present()

#' @rdname conditions
#' @export
no_beepers_present <- function() .no_beepers_present()

#' @rdname conditions
#' @export
karel_has_beepers <- function() .karel_has_beepers()

#' @rdname conditions
#' @export
karel_has_no_beepers <- function() .karel_has_no_beepers()

#' @rdname conditions
#' @export
facing_east <- function() .facing_east()

#' @rdname conditions
#' @export
facing_west <- function() .facing_west()

#' @rdname conditions
#' @export
facing_north <- function() .facing_north()

#' @rdname conditions
#' @export
facing_south <- function() .facing_south()

# ------------------------------------------------------------------------------

#' Turn on Karel's superpowers
#'
#' After running \code{load_super_karel()}, Karel can also turn right and turn
#' around with \code{turn_right()} and \code{turn_around()}. If these
#' superpowers aren't loaded, then these functions won't be available and Karel
#' can't use them.
#'
#' @return It doesn't return anything but attaches to the global environment the
#'   functions \code{turn_right()} and \code{turn_around()}.
#'
#' @examples
#' generate_world("mundo001")
#' load_super_karel()
#' turn_around()
#' turn_right()
#' if (interactive()) run_actions()
#'
#' @seealso \code{\link{actions}} \code{\link{generate_world}}
#'   \code{\link{run_actions}}
#' @export
#'
load_super_karel <- function() .load_super_karel()

#' @rdname actions
#' @export
turn_right <- function() .turn_right(lang = "en")

#' @rdname actions
#' @export
turn_around <- function() .turn_around(lang = "en")

# ------------------------------------------------------------------------------

#' Get Karel's environment
#'
#' This function returns the environment called pkg_env created by the package.
#' It's useful for debugging and checking. It's an internal function, not
#' thought to be used by students, but can be used with karel:::get_pkg_env().
#'
#' @return An enviroment with objects that represent Karel's world.
#'
#' @details \code{pkg_env} is an environment created inside the package to store
#'   and share between functions all the objects related to Karel's world and
#'   its state. Since the functions that will be used by the students should be
#'   simple and without arguments (for example, \code{move()}), these functions
#'   modify internally \code{pkg_env}.
#'
#'   The components of this environment are:
#'   \enumerate{
#'     \item \code{nx}: size of Karel's world, number of cells in x-axis.
#'     \item \code{ny}: size of Karel's world, number of cells in y-axis.
#'     \item \code{hor_walls}: a data.frame with a row for each horizontal wall
#'     in Karel's world and 3 columns: x (coordinate of the start of the wall in
#'     the x axis), y (coordinate of the start of the wall in the y axis), lgth
#'     (length of the wall, in number of cells it covers). If it is NULL, there
#'     are no horizontal walls in the world.
#'     \item \code{ver_walls}: a data.frame with a row for each vertical wall in
#'     Karel's world and 3 columns: x (coordinate of the start of the wall in
#'     the x axis), y (coordinate of the start of the wall in the y axis), lgth
#'     (length of the wall, in number of cells it covers). If it takes the value
#'     NULL, there are no vertical walls in the world.
#'     \item \code{open_moves}: a nx x ny x 4 array of TRUE/FALSE values
#'     indicating if Karel can move to each direction from a given position. For
#'     example, if Karel is in the bottom left corner, which is cell [1, 1], it
#'     can't go south or left, so we have both open_moves[1, 1, 3] and
#'     open_moves[1, 1, 4] set to FALSE. Depending on the existing walls it
#'     could move south or north, so open_moves[1, 1, 1] and open_moves[1, 1, 2]
#'     could be TRUE or FALSE. Taking into account the size of the world and the
#'     walls, this array is created by the internal function
#'     \code{\link{generate_open_moves}}.
#'     \item \code{karel}: a data.frame with a row for each moment, in which
#'     each state of Karel is recorded throughout the execution of its actions.
#'     It has 4 columns: karel_x (Karel's x-axis coordinate), karel_y (Karel's
#'     y-axis coordinate), karel_dir (the direction Karel is facing, 1 east, 2
#'     north, 3 west, or 4 south), and moment (integer value indicating each
#'     moment).
#'     \item \code{dir_now}: current Karel's facing direction.
#'     \item \code{x_now}: x-axis coordinate of Karel's current position.
#'     \item \code{y_now}: y-axis coordinate of Karel's current position.
#'     \item \code{moment}: current moment (integer value).
#'     \item \code{beepers_any}: total amount of beepers present in the world at
#'     this moment.
#'     \item \code{beepers_bag}: number of beepers that Karel has available in
#'     its bag at the moment. Karel can put beepers if it has beepers in its
#'     bag. It can take the value Inf.
#'     \item \code{beepers_now}: a data.frame with as many rows as cells with
#'     beepers in the world and 5 columns: \code{x} and \code{y} for the
#'     coordinates of the cell, \code{cell} is the number of the cell counting
#'     as cell number 1 the cell in the bottom left corner and going upwards by
#'     row (meaning cell number 2 would be the cell in coordinates x=2 and y=1),
#'     \code{n} the number of beepers in this cell and \code{moment} the moment
#'     in which this state of the world corresponds to. It is created by the
#'     internal function  \code{\link{create_beepers}}.
#'     \item \code{beepers_all}: a data.frame with the same structure as
#'     \code{beepers_now}. While \code{beepers_now} only has current state of
#'     beepers, \code{beepers_all} acummulates all states for the animation,
#'     binding the rows of \code{beepers_now} and \code{beepers_all} after each
#'     action.
#'     \item \code{base_plot}: the initial plot of the world, with its size and
#'     all the walls if there are any. It doesn't show Karel or the beepers,
#'     since those things can change with time. This is the base plot that is
#'     used later to produce the animation. This plot is created by the internal
#'     function \code{\link{plot_base_world}}.
#'   }
#'
#' @examples
#' generate_world("mundo001")
#' if (interactive()) karel:::get_pkg_env()
#'
get_pkg_env <- function() .get_pkg_env()

# ------------------------------------------------------------------------------

#' Plot the world at a given time
#'
#' This function plots Karel'w wort at the requested time. Initially, time is 1
#' and with each action that Karel performs, time is incremented by one. Current
#' time is stored in \code{pkg_env$moment}. This function is useful for
#' debugging and to get static images to be used in the examples in the handouts
#' for students. It's an internal function, not thought to be used by students,
#' but can be used with karel:::plot_static_world().
#'
#' @param time The requested time
#'
#' @return Prints the plot.
#'
#' @examples
#' if (interactive()) karel:::plot_static_world(1)
#'
plot_static_world <- function(time) .plot_static_world(time = time, lang = "en")