#' Manage relationships between datasets using `join_keys`

#' @order 1

#' @name join_keys

#'

#' @usage ## Constructor, getter and setter

#' join_keys(...)

#'

#' @description

#' Facilitates the creation and retrieval of relationships between datasets.

#' `join_keys` class extends `list` and contains keys connecting pairs of datasets.

#' Each element of the list contains keys for specific dataset.

#' Each dataset can have a relationship with itself (primary key) and with other datasets.

#'

#' Note that `join_keys` list is symmetrical and assumes a default direction, that is:

#' when keys are set between `ds1` and `ds2`, it defines `ds1` as the parent

#' in a parent-child relationship and the mapping is automatically mirrored between

#' `ds2` and `ds1`.

#'

#' @section Methods (by class):

#' - `join_keys()`: Returns an empty `join_keys` object when called without arguments.

#' - `join_keys(join_keys)`: Returns itself.

#' - `join_keys(teal_data)`: Returns the `join_keys` object contained in `teal_data` object.

#' - `join_keys(...)`: Creates a new object with one or more `join_key_set` parameters.

#'

#' @param ... optional,

#' - either `teal_data` or `join_keys` object to extract `join_keys`

#' - or any number of `join_key_set` objects to create `join_keys`

#' - or nothing to create an empty `join_keys`

#' @param value For `x[i, j, directed = TRUE)] <- value` (named/unnamed `character`)

#' Column mapping between datasets.

#'

#' For `join_keys(x) <- value`: (`join_key_set` or list of `join_key_set`) relationship

#' pairs to add to `join_keys` list.

#'

#'

#' @return `join_keys` object.

#'

#' @examples

#' # Creating a new join keys ----

#'

#' jk <- join_keys(

#'   join_key("ds1", "ds1", "pk1"),

#'   join_key("ds2", "ds2", "pk2"),

#'   join_key("ds3", "ds3", "pk3"),

#'   join_key("ds1", "ds2", c(pk1 = "pk2")),

#'   join_key("ds1", "ds3", c(pk1 = "pk3"))

#' )

#'

#' jk

#'

#' @export

#'

#' @seealso [join_key()] for creating `join_keys_set`,

#' [parents()] for parent operations,

#' [teal_data()] for `teal_data` constructor _and_

#' [default_cdisc_join_keys] for default CDISC keys.

#'

join_keys <- function(...) {

  }

  } else {

  }

}

#' @rdname join_keys

#' @order 1

#' @export

join_keys.default <- function(...) {

}

#' @rdname join_keys

#' @order 1

#' @export

join_keys.join_keys <- function(...) {

}

#' @rdname join_keys

#' @order 1

#' @export

join_keys.teal_data <- function(...) {

}

#' @rdname join_keys

#' @order 5

#'

#' @section Functions:

#' - `join_keys(x) <- value`: Assignment of the `join_keys` in object with `value`.

#' `value` needs to be an object of class `join_keys` or `join_key_set`.

#'

#' @param x (`join_keys`) empty object to set the new relationship pairs.

#' `x` is typically an object of `join_keys` class. When called with the `join_keys(x)`

#' or `join_keys(x) <- value` then it can also take a supported class (`teal_data`, `join_keys`)

#'

#' @export

`join_keys<-` <- function(x, value) {

}

#' @rdname join_keys

#' @order 5

#' @export

#' @examples

#' # Assigning keys via join_keys(x)[i, j] <- value ----

#'

#' obj <- join_keys()

#' # or

#' obj <- teal_data()

#'

#' join_keys(obj)["ds1", "ds1"] <- "pk1"

#' join_keys(obj)["ds2", "ds2"] <- "pk2"

#' join_keys(obj)["ds3", "ds3"] <- "pk3"

#' join_keys(obj)["ds1", "ds2"] <- c(pk1 = "pk2")

#' join_keys(obj)["ds1", "ds3"] <- c(pk1 = "pk3")

#'

#' identical(jk, join_keys(obj))

`join_keys<-.join_keys` <- function(x, value) {

}

#' @rdname join_keys

#' @order 5

#' @export

#' @examples

#' # Setter for join_keys within teal_data ----

#'

#' td <- teal_data()

#' join_keys(td) <- jk

#'

#' join_keys(td)["ds1", "ds2"] <- "new_key"

#' join_keys(td) <- c(join_keys(td), join_keys(join_key("ds3", "ds2", "key3")))

#' join_keys(td)

`join_keys<-.teal_data` <- function(x, value) {

}

#' Internal constructor

#'

#' @return an empty `join_keys` list

#'

#' @keywords internal

new_join_keys <- function() {

  )

}

#' @rdname join_keys

#' @order 2

#'

#' @section Functions:

#' - `x[names]`: Returns a subset of the `join_keys` object for

#' given `names`, including parent `names` and symmetric mirror keys between

#' `names` in the result.

#' - `x[i, j]`: Returns join keys between datasets `i` and `j`,

#'   including implicit keys inferred from their relationship with a parent.

#'

#' @param i,j indices specifying elements to extract or replace. Index should be a

#' a character vector, but it can also take numeric, logical, `NULL` or missing.

#'

#' @export

#'

#' @examples

#' # Getter for join_keys ---

#'

#' jk["ds1", "ds2"]

#'

#' # Subsetting join_keys ----

#'

#' jk["ds1"]

#' jk[1:2]

#' jk[c("ds1", "ds2")]

#'

`[.join_keys` <- function(x, i, j) {

    # because:

    # - list(a = 1)[] returns list(a = 1)

    # - data.frame(a = 1)[] returns data.frame(a = 1)

    # because list(a = 1)[NULL] returns NULL

    # data.frame(a = 1)[NULL, NULL] returns data.frame(

    if (

      ) ||

        )

    ) {

      )

    }

    # ie. select all keys which have j as dataset_2

    # since list is symmetrical it is equivalent to selecting by i

  }

  )

  # Convert integer/logical index to named index

  }

  # When retrieving a relationship pair, it will also return the symmetric key

  # Need to iterate on a mutating queue if subset of a dataset will also

  #  select its parent as that parent might have relationships with others

  #  already selected.

    }

    # Add primary key of parent

    }

  }

}

#' @rdname join_keys

#' @order 2

#'

#' @param directed (`logical(1)`) Flag that indicates whether it should create

#' a parent-child relationship between the datasets.

#'  - `TRUE` (default) `dataset_1` is the parent of `dataset_2`;

#'  - `FALSE` when the relationship is undirected.

#' @section Functions:

#' - `x[i, j] <- value`: Assignment of a key to pair `(i, j)`.

#' - `x[i] <- value`: This (without `j` parameter) **is not** a supported

#' operation for `join_keys`.

#' - `join_keys(x)[i, j] <- value`: Assignment to `join_keys` object stored in `x`,

#' such as a `teal_data` object or `join_keys` object itself.

#'

#' @export

#' @examples

#' # Setting a new primary key ---

#'

#' jk["ds4", "ds4"] <- "pk4"

#' jk["ds5", "ds5"] <- "pk5"

#'

#' # Setting a single relationship pair ---

#'

#' jk["ds1", "ds4"] <- c("pk1" = "pk4")

#'

#' # Removing a key ---

#'

#' jk["ds5", "ds5"] <- NULL

`[<-.join_keys` <- function(x, i, j, directed = TRUE, value) {

  } else if (

    ) ||

      )

  ) {

    )

  }

  # Handle join key removal separately

  }

}

#' @rdname join_keys

#'

#' @order 1000

#' @usage ## Preferred method is x[i, j] <- value

#' x[[i]][[j]] <- value

#'

#' @section Functions:

#' - `x[[i]][[j]] <- value`: It is equivalent as  `x[i, j] <- value`.

#'

#' @export

#' @examples

#' # Setting via x[[i]] <- value ---

#'

#' jk <- join_keys()

#' jk[["ds6"]][["ds6"]] <- "pk6"

#' jk[["ds7"]] <- list(ds7 = "pk7", ds6 = c(pk7 = "pk6"))

#' jk[["ds7"]][["ds7"]] <- NULL # removes key

#'

#' jk

#'

#' @noRd

`[[<-.join_keys` <- function(x, i, value) {

  )

  }

  # Normalize values

  })

  # Check if multiple modifications don't have a conflict

      )

    },

  )

  # Safe to do as duplicated are the same

  # Keep only elements with length > 0L

  # Remove classes to use list-based get/assign operations

  # In case a pair is removed, also remove the symmetric pair and update parents

  }

  # Iterate on all new values to create symmetrical pair

    # Invert key

    # Assign symmetrical

  }

  # Remove NULL or empty keys

  #

  # restore class

}

setOldClass("join_keys")

#' Reproducible data

#'

#' Reproducible data container class. Inherits code tracking behavior from [`teal.code::qenv-class`].

#'

#' This class provides an isolated environment in which to store and process data with all code being recorded.

#' The environment, code, data set names, and data joining keys are stored in their respective slots.

#' These slots should never be accessed directly, use the provided get/set functions.

#'

#' As code is evaluated in `teal_data`, messages and warnings are stored in their respective slots.

#' If errors are raised, a `qenv.error` object is returned.

#'

#' @name teal_data-class

#' @rdname teal_data-class

#'

#' @slot .xData (`environment`) environment containing data sets and possibly

#'  auxiliary variables.

#'  Access variables with [get()], [`$`], [teal.code::get_var()] or [`[[`].

#'  No setter provided. Evaluate code to add variables into `@.xData`.

#' @slot code (`list` of `character`) representing code necessary to reproduce the contents of `qenv`.

#'  Access with [teal.code::get_code()].

#'  No setter provided. Evaluate code to append code to the slot.

#' @slot join_keys (`join_keys`) object specifying joining keys for data sets in

#' `@.xData`.

#'  Access or modify with [join_keys()].

#' @slot verified (`logical(1)`) flag signifying that code in `@code` has been

#'  proven to yield contents of `@.xData`.

#'  Used internally. See [`verify()`] for more details.

#'

#' @inheritSection teal.code::`qenv-class` Code

#'

#' @import teal.code

#' @keywords internal

setClass(

  Class = "teal_data",

  contains = "qenv",

  slots = c(join_keys = "join_keys", verified = "logical"),

  prototype = list(

    join_keys = join_keys(),

    verified = logical(0)

  )

)

#' It initializes the `teal_data` class

#'

#' Accepts .xData as a list and converts it to an environment before initializing

#' parent constructor (`qenv`).

#' @noRd

setMethod(

  "initialize",

  "teal_data",

  function(.Object, .xData = list(), join_keys = join_keys(), code = list(), ...) { # nolint: object_name.

    # Allow .xData to be a list and convert it to an environment

    }

    }

    }

    }

      ...

    )

  }

)

#' Reshape code to the list

#'

#' List will be divided by the calls. Each element of the list contains `id` and `dependency` attributes.

#'

#' @param code `character` with the code.

#'

#' @return list of `character`s of the length equal to the number of calls in `code`.

#'

#' @keywords internal

#' @noRd

code2list <- function(code) {

  }

    })

  } else {

    # empty code like "", or just comments

  }

}

#' Topological graph sort

#'

#' Graph is a `list` which for each node contains a vector of child nodes

#' in the returned list, parents appear before their children.

#'

#' Implementation of `Kahn` algorithm with a modification to maintain the order of input elements.

#'

#' @param graph (`named list`) with node vector elements

#' @keywords internal

topological_sort <- function(graph) {

  # compute in-degrees

    }

  }

    }

  }

  # sort

  }

      }

    }

  }

    )

  } else {

  }

}

#' Checks whether a graph is a `Directed Acyclic Graph (DAG)`

#'

#' @inheritParams topological_sort

#' @return `logical(1)` `TRUE` if the graph is a `DAG`; `FALSE` otherwise

#' @keywords internal

is_dag <- function(graph) {

}

#' Create a relationship between a pair of datasets

#'

#' @description

#' `r lifecycle::badge("stable")`

#'

#' Create a relationship between two datasets, `dataset_1` and `dataset_2`.

#' By default, this function establishes a directed relationship with `dataset_1` as the parent.

#' If `dataset_2` is not specified, the function creates a primary key for `dataset_1`.

#'

#' @param dataset_1,dataset_2 (`character(1)`) Dataset names. When `dataset_2` is omitted,

#' a primary key for `dataset_1` is created.

#' @param keys (optionally named `character`) Column mapping between the datasets,

#' where `names(keys)` maps columns in `dataset_1` corresponding to columns of

#' `dataset_2` given by the elements of `keys`.

#' - If unnamed, the same column names are used for both datasets.

#' - If any element of the `keys` vector is empty with a non-empty name, then the name is

#' used for both datasets.

#' @param directed (`logical(1)`) Flag that indicates whether it should create

#' a parent-child relationship between the datasets.

#'  - `TRUE` (default) `dataset_1` is the parent of `dataset_2`;

#'  - `FALSE` when the relationship is undirected.

#'

#' @return object of class `join_key_set` to be passed into `join_keys` function.

#'

#' @examples

#' join_key("d1", "d2", c("A"))

#' join_key("d1", "d2", c("A" = "B"))

#' join_key("d1", "d2", c("A" = "B", "C"))

#'

#' @export

#' @seealso [join_keys()], [parents()]

#'

join_key <- function(dataset_1, dataset_2 = dataset_1, keys, directed = TRUE) {

    }

    # Remove keys with empty value and without name

    }

    # Set name of keys without one: c("A") -> c("A" = "A")

    }

    # Set value of keys with empty string, but non-empty name: c("A" = "") -> c("A" = "A")

    }

    }

  } else {

  }

  } else {

  }

      )

    ),

  )

}

#' Test if two objects are (nearly) equal

#'

#' `all.equal(target, current)` is a utility to compare `join_keys` objects target

#' and current testing `near equality`.

#'

#' If they are different, comparison is still made to some extent, and a report

#' of the differences is returned.

#' Do not use `all.equal` directly in if expressions—either use `isTRUE(all.equal(....))`

#' or identical if appropriate.

#'

#' The parents attribute comparison tolerates `NULL` and empty lists and will find

#' no difference.

#'

#' The list containing all the relationships is treated like a map and ignores

#' entries with `NULL` if they exist.

#'

#' @inheritParams base::all.equal

#' @param ... further arguments for different methods. Not used with `join_keys`.

#'

#' @seealso [base::all.equal()]

#' @keywords internal

#'

all.equal.join_keys <- function(target, current, ...) {

    # Keep only non-list attributes

    } else {

    }

    # Remove nulls

    # Sort named components, preserving positions of unnamed

    }

  }

}

#' Variable labels

#'

#' Get or set variable labels in a `data.frame`.

#'

#' @details Variable labels can be stored as a `label` attribute set on individual variables.

#' These functions get or set this attribute, either on all (`col_labels`) or some variables (`col_relabel`).

#'

#' @param x (`data.frame` or `DataFrame`) data object

#' @param fill (`logical(1)`) specifying what to return if variable has no label

#' @param value (`character`) vector of variable labels of length equal to number of columns in `x`;

#'  if named, names must match variable names in `x` and will be used as key to set labels;

#'  use `NA` to remove label from variable

#' @param ... name-value pairs, where name corresponds to a variable name in `x`

#'  and value is the new variable label; use `NA` to remove label from variable

#'

#' @return

#' For `col_labels`, named character vector of variable labels, the names being the corresponding variable names.

#' If the `label` attribute is missing, the vector elements will be

#' the variable names themselves if `fill = TRUE` and `NA` if `fill = FALSE`.

#'

#' For `col_labels<-` and `col_relabel`, copy of `x` with variable labels modified.

#'

#' @examples

#' x <- iris

#' col_labels(x)

#' col_labels(x) <- paste("label for", names(iris))

#' col_labels(x)

#' y <- col_relabel(x, Sepal.Length = "Sepal Length of iris flower")

#' col_labels(y)

#'

#' @source These functions were taken from

#' [formatters](https://cran.r-project.org/package=formatters) package, to reduce the complexity of

#' the dependency tree and rewritten.

#'

#' @rdname col_labels

#' @export

#'

col_labels <- function(x, fill = FALSE) {

  }

      )

    },

  )

      } else {

      }

  }

}

#' @rdname col_labels

#' @export

`col_labels<-` <- function(x, value) {

  )

    } else {

    }

    } else {

    }

  }

}

#' @rdname col_labels

#' @export

col_relabel <- function(x, ...) {

  }

    } else {

    }

  }

}

#' The names of a `join_keys` object

#'

#' @inheritParams base::`names<-`

#' @export

`names<-.join_keys` <- function(x, value) {

  # Update inner keys

    # Change 2nd-tier first

    }

    # Change in first tier

    # changing name in the parents

    }

  }

}

#' Comprehensive data integration function for `teal` applications

#'

#' @description

#' `r lifecycle::badge("stable")`

#'

#' Universal function to pass data to teal application.

#'

#' @param ... any number of objects (presumably data objects) provided as `name = value` pairs.

#'

#' @param join_keys (`join_keys` or single `join_key_set`)

#' optional object with datasets column names used for joining.

#' If empty then no joins between pairs of objects.

#'

#' @param code (`character`, `language`) optional code to reproduce the datasets provided in `...`.

#'  Note this code is not executed and the `teal_data` may not be reproducible

#'

#'  Use [verify()] to verify code reproducibility .

#'

#' @return A `teal_data` object.

#'

#' @export

#'

#' @examples

#' teal_data(x1 = iris, x2 = mtcars)

#'

teal_data <- function(...,

                      join_keys = teal.data::join_keys(),

                      code = character(0)) {

  }

  }

  )

}

#' Get code from `teal_data` object

#'

#' Retrieve code from `teal_data` object.

#'

#' Retrieve code stored in `@code`, which (in principle) can be used to recreate

#' all objects found in the environment (`@.xData`).

#' Use `names` to limit the code to one or more of the datasets enumerated in

#' the environment.

#'

#' @section Extracting dataset-specific code:

#' When `names` is specified, the code returned will be limited  to the lines needed to _create_

#' the requested datasets. The code stored in the `@code` slot is analyzed statically to determine

#' which lines the datasets of interest depend upon. The analysis works well when objects are created

#' with standard infix assignment operators (see `?assignOps`) but it can fail in some situations.

#'

#' Consider the following examples:

#'

#' _Case 1: Usual assignments._

#' ```r

#' data <- teal_data() |>

#'   within({

#'     foo <- function(x) {

#'       x + 1

#'     }

#'     x <- 0

#'     y <- foo(x)

#'   })

#' get_code(data, names = "y")

#' ```

#' `x` has no dependencies, so `get_code(data, names = "x")` will return only the second call.\cr

#' `y` depends on `x` and `foo`, so `get_code(data, names = "y")` will contain all three calls.

#'

#' _Case 2: Some objects are created by a function's side effects._

#' ```r

#' data <- teal_data() |>

#'   within({

#'     foo <- function() {

#'       x <<- x + 1

#'     }

#'     x <- 0

#'     foo()

#'     y <- x

#'   })

#' get_code(data, names = "y")

#' ```

#' Here, `y` depends on `x` but `x` is modified by `foo` as a side effect (not by reassignment)

#' and so `get_code(data, names = "y")` will not return the `foo()` call.\cr

#' To overcome this limitation, code dependencies can be specified manually.

#' Lines where side effects occur can be flagged by adding "`# @linksto <object name>`" at the end.\cr

#' Note that `within` evaluates code passed to `expr` as is and comments are ignored.

#' In order to include comments in code one must use the `eval_code` function instead.

#'

#' ```r

#' data <- teal_data() |>

#'   eval_code("

#'     foo <- function() {

#'       x <<- x + 1

#'     }

#'     x <- 0

#'     foo() # @linksto x

#'     y <- x

#'   ")

#' get_code(data, names = "y")

#' ```

#' Now the `foo()` call will be properly included in the code required to recreate `y`.

#'

#' Note that two functions that create objects as side effects, `assign` and `data`, are handled automatically.

#'

#' Here are known cases where manual tagging is necessary:

#' - non-standard assignment operators, _e.g._ `%<>%`

#' - objects used as conditions in `if` statements: `if (<condition>)`

#' - objects used to iterate over in `for` loops: `for(i in <sequence>)`

#' - creating and evaluating language objects, _e.g._ `eval(<call>)`

#'

#'

#' @param object (`teal_data`)

#' @param datanames `r lifecycle::badge("deprecated")` (`character`) vector of dataset names to return the code for.

#' For more details see the "Extracting dataset-specific code" section. Use `names` instead.

#' @param names (`character`) Successor of `datanames`. Vector of dataset names to return the code for.

#' For more details see the "Extracting dataset-specific code" section.

#' @param deparse (`logical`) flag specifying whether to return code as `character` (`deparse = TRUE`) or as

#' `expression` (`deparse = FALSE`).

#' @param ... Parameters passed to internal methods. Currently, the only supported parameter is `check_names`

#' (`logical(1)`) flag,  which is `TRUE` by default. Function warns about missing objects, if they do not exist in

#' `code` but are passed in `datanames`. To remove the warning, set `check_names = FALSE`.

#'

#' @return

#' Either a character string or an expression. If `names` is used to request a specific dataset,

#' only code that _creates_ that dataset (not code that uses it) is returned. Otherwise, all contents of `@code`.

#'

#' @examples

#' tdata1 <- teal_data()

#' tdata1 <- within(tdata1, {

#'   a <- 1

#'   b <- a^5

#'   c <- list(x = 2)

#' })

#' get_code(tdata1)

#' get_code(tdata1, names = "a")

#' get_code(tdata1, names = "b")

#'

#' tdata2 <- teal_data(x1 = iris, code = "x1 <- iris")

#' get_code(tdata2)

#' get_code(verify(tdata2))

#'

#' @rdname get_code

#' @aliases get_code,teal_data-method

#'

#' @export

setMethod("get_code",

  signature = "teal_data",

  definition = function(object, deparse = TRUE, names = NULL, datanames = lifecycle::deprecated(), ...) {

      )

    }

    }

  }

)

#' Verify code reproducibility

#'

#' Checks whether code in `teal_data` object reproduces the stored objects.

#'

#' If objects created by code in the `@code` slot of `x` are `all_equal` to the

#' contents of the environment (`@.xData` slot),

#' the function updates the `@verified` slot to `TRUE` in the returned `teal_data` object.

#' Once verified, the slot will always be set to `TRUE`.

#' If the `@code` fails to recreate objects in `teal_data`'s environment, an

#' error is raised.

#'

#' @return Input `teal_data` object or error.

#'

#' @param x `teal_data` object

#' @examples

#' tdata1 <- teal_data()

#' tdata1 <- within(tdata1, {

#'   a <- 1

#'   b <- a^5

#'   c <- list(x = 2)

#' })

#' verify(tdata1)

#'

#' tdata2 <- teal_data(x1 = iris, code = "x1 <- iris")

#' verify(tdata2)

#' verify(tdata2)@verified

#' tdata2@verified

#'

#' tdata3 <- teal_data()

#' tdata3 <- within(tdata3, {

#'   stop("error")

#' })

#' try(verify(tdata3)) # fails

#'

#'

#' a <- 1

#' b <- a + 2

#' c <- list(x = 2)

#' d <- 5

#' tdata4 <- teal_data(

#'   a = a, b = b, c = c, d = d,

#'   code = "a <- 1

#'           b <- a

#'           c <- list(x = 2)

#'           e <- 1"

#' )

#' tdata4

#' \dontrun{

#' verify(tdata4) # fails

#' }

#'

#' @name verify

#' @rdname verify

#' @aliases verify,teal_data-method

#' @aliases verify,qenv.error-method

#'

#' @export

setMethod("verify", signature = "teal_data", definition = function(x) {

  }

  }

  } else {

      },

    )

      )

    }

      )

    }

      )

    }

  }

})

setMethod("verify", signature = "qenv.error", definition = function(x) {

})

#' Check Compatibility of keys

#'

#' Helper function to assert if two key sets contain incompatible keys.

#'

#' @return Returns `TRUE` if successful, otherwise raises error.

#' @keywords internal

assert_compatible_keys <- function(join_key_1, join_key_2) {

    )

  }

  # if first datasets and the second datasets match and keys

  # must contain the same named elements

    }

  }

  # if first dataset of join_key_1 matches second dataset of join_key_2

  # and the first dataset of join_key_2 must match second dataset of join_key_1

  # and keys must contain the same elements but with names and values swapped

    if (

    ) {

    }

  }

  # otherwise they are compatible

}

#' Validate parent-child key

#'

#' Helper function checks the parent-child relations are valid.

#'

#' @param x (`join_keys`) object to assert validity of relations

#'

#' @return `join_keys` invisibly

#'

#' @keywords internal

assert_parent_child <- function(x) {

        }

      }

    }

  }

}

#' Verify key set compatibility

#'

#' Helper function to ensuring compatibility between two sets of keys

#'

#' @return Returns `TRUE` if successful, otherwise raises error.

#' @keywords internal

assert_compatible_keys2 <- function(x, y) {

  # Helper to flatten join_keys / join_key_set

      },

    )

  }

    }

  }

}

#' Updates the keys of the datasets based on the parents

#'

#' @param x (`join_keys`) object to update the keys.

#'

#' @return (`self`) invisibly for chaining

#'

#' @keywords internal

update_keys_given_parents <- function(x) {

        # both has the same parent -> common keys to parent

        # No common keys between datasets - leave empty

        )

      }

    }

  }

  # check parent child relation

}

#' Get and set parents in `join_keys` object

#'

#' `parents()` facilitates the creation of dependencies between datasets by

#' assigning a parent-child relationship.

#'

#' Each element is defined by a `list` element, where `list("child" = "parent")`.

#'

#' @param x (`join_keys` or `teal_data`) object that contains "parents" information

#' to retrieve or manipulate.

#'

#' @return a `list` of `character` representing the parents.

#'

#' @export

#' @seealso [join_keys()]

parents <- function(x) {

}

#' @describeIn parents Retrieves parents of `join_keys` object.

#' @export

#' @examples

#' # Get parents of join_keys ---

#'

#' jk <- default_cdisc_join_keys["ADEX"]

#' parents(jk)

parents.join_keys <- function(x) {

}

#' @describeIn parents Retrieves parents of `join_keys` inside `teal_data` object.

#' @export

#' @examples

#' # Get parents of join_keys inside teal_data object ---

#'

#' td <- teal_data(

#'   ADSL = rADSL,

#'   ADTTE = rADTTE,

#'   ADRS = rADRS,

#'   join_keys = default_cdisc_join_keys[c("ADSL", "ADTTE", "ADRS")]

#' )

#' parents(td)

parents.teal_data <- function(x) {

}

#' @describeIn parents Assignment of parents in `join_keys` object.

#'

#' @param value (`named list`) of `character` vectors.

#'

#' @export

`parents<-` <- function(x, value) {

}

#' @describeIn parents Assignment of parents of `join_keys` object.

#' @export

#' @examples

#' # Assignment of parents ---

#'

#' jk <- join_keys(

#'   join_key("ds1", "ds2", "id"),

#'   join_key("ds5", "ds6", "id"),

#'   join_key("ds7", "ds6", "id")

#' )

#'

#' parents(jk) <- list(ds2 = "ds1")

#'

#' # Setting individual parent-child relationship

#'

#' parents(jk)["ds6"] <- "ds5"

#' parents(jk)["ds7"] <- "ds6"

`parents<-.join_keys` <- function(x, value) {

    # Custom .var.name so it is verbose and helpful for users

      ),

    )

    }

  }

  }

}

#' @describeIn parents Assignment of parents of `join_keys` inside `teal_data` object.

#' @export

#' @examples

#' # Assignment of parents of join_keys inside teal_data object ---

#'

#' parents(td) <- list("ADTTE" = "ADSL") # replace existing

#' parents(td)["ADRS"] <- "ADSL" # add new parent

`parents<-.teal_data` <- function(x, value) {

}

#' @describeIn parents Getter for individual parent.

#'

#' @param dataset_name (`character(1)`) Name of dataset to query on their parent.

#'

#' @return For `parent(x, dataset_name)` returns `NULL` if parent does not exist.

#'

#' @export

#'

#' @examples

#' # Get individual parent ---

#'

#' parent(jk, "ds2")

#' parent(td, "ADTTE")