---
title: "Apply Model Modules Using A Simple And Consistent Syntax"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Apply Model Modules Using A Simple And Consistent Syntax}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE)
```
```{r results='hide', message=FALSE, warning=F}
library(ready4) 
```

## Motivation
To be used in health economic analyses, model modules need to be called using a programming syntax. Ideally that syntax should be relatively simple, with the name and description of each command reliably communicating the category of operations it performs.

## Implementation
`ready4` provides a simple syntax that is used by all model modules developed with the [`ready4` framework](https://www.ready4-dev.com/).

## Use
A table that itemises `ready4` commands along with examples of how these commands are used can be ingested from a periodically updated database using `get_methods_tb`. In the below example we will search for examples of where that syntax has been used by modules from the [readyforwhatsnext model](https://readyforwhatsnext.org/). The value supplied to the `gh_repo_1L_chr` argument specifies the repository in which a dataset of readyforwhatsnext module libraries is stored.

```{r echo=FALSE, eval=FALSE}
# Not run
# x <- make_methods_tb(gh_repo_1L_chr = "ready4-dev/ready4")
```
```{r}
x <- get_methods_tb(gh_repo_1L_chr = "ready4-dev/ready4")
```

### Core commands
A HTML table of `ready4`'s core commands and examples of the use of each command can be displayed using the `print_methods` function, using the `return_1L_chr = "core"` argument. 

```{r}
print_methods(x,
              return_1L_chr = "core",
              scroll_width_1L_chr = "100%") 
```

### Applying commands to module "slots"
Each of the "core" commands also has a "slot" version, which applies the command to a specified slot (a named element of a module). Two of these "slot" methods can also be used for additional purposes:

 - [procureSlot](https://ready4-dev.github.io/ready4/reference/procureSlot-methods.html) is a "getter" method - its default behaviour is to return the value of a specified slot. If the argument `use_procure_mthd_1L_lgl = T` is included in the method call, `procureSlot` will instead apply the `procure` method to a specified slot.
 
 - [renewSlot](https://ready4-dev.github.io/ready4/reference/procureSlot-methods.html) is a "setter" method - if any value other than "use_renew_mthd" (the default) is passed to the `new_val_xx` argument, that value will be assigned to the specified slot.
 
A HTML table of slot commands and relevant examples can be displayed using the `print_methods` function, using the `return_1L_chr = "slot"` argument.

```{r}
print_methods(x,
              return_1L_chr = "slot",
              scroll_width_1L_chr = "100%")
```

### Extended commands
Finally, there are a small number of other commands that are more general extensions of the core commands. Currently, these extended commands are all variants on the `author` command, with each extension specifying the type of output to be authored by the method. A HTML table of the extended generics bundled with `ready4` can be displayed using the `print_methods` function, using the `return_1L_chr = "extended"` argument.

```{r}
print_methods(x,
              exclude_mthds_for_chr = "Ready4Module",
              return_1L_chr = "extended",
              scroll_width_1L_chr = "100%")
```