### Create a new module with a custom jamovi installation path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/create.md

This example shows how to specify a custom path to a jamovi installation. This is useful if your jamovi installation is not in the default location or if you need to target a specific version for preparation.

```r
jmvtools::create(path = "mymodule", home = "/opt/jamovi")
```

--------------------------------

### Get Started with a New Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This snippet demonstrates the initial steps to create a new jamovi module and load the jmvtools library.

```r
library(jmvtools)

```

```r
jmvtools::create("mystats")
```

--------------------------------

### Set up Module Build and Install in Script

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This script prepares and installs a jamovi module from a specified path, including a check for errors before installation.

```r
#!/usr/bin/Rscript
library(jmvtools)

# Build and install a module
module_path <- "~/projects/mymodule"
jmvtools::prepare(pkg = module_path)
if (!("ERROR" %in% ls())) {
    jmvtools::install(pkg = module_path)
}
```

--------------------------------

### install()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/INDEX.md

Build and install a jamovi module into jamovi.

```APIDOC
## install()

### Description
Build and install a jamovi module into jamovi.

### Function Signature
`install(path)`

### Parameters
#### Path Parameters
- **path** (character) - Required - The path to the jamovi module source directory.
```

--------------------------------

### Install Module into jamovi

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

The `install` function validates the module (internally calling `prepare`) and then copies it into the jamovi installation directory for immediate testing. Use this after making changes to your module.

```r
jmvtools::install(pkg = "mymodule")
```

--------------------------------

### Install Module for Testing

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Use `install()` to install a jamovi module into the jamovi application directory for testing. This allows you to see your module within jamovi.

```r
jmvtools::install("mymodule")
```

--------------------------------

### Check Default Jamovi Installation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/check.md

Use this snippet to check the default jamovi installation. No setup is required if jamovi is in a standard location.

```r
jmvtools::check()
```

--------------------------------

### Quick Start: jmvtools Module Development Workflow

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/README.md

Demonstrates the basic workflow for creating, adding analyses to, preparing, and installing a jamovi module using jmvtools. Includes steps for initializing translations.

```r
# Load jmvtools
library(jmvtools)

# Create a new module
jmvtools::create("mymodule")

# Add an analysis
jmvtools::addAnalysis("mytest", "My Test")

# Prepare for testing (validate only)
jmvtools::prepare(pkg = "mymodule")

# Install to jamovi for testing
jmvtools::install(pkg = "mymodule")

# Add translations
jmvtools::i18nCreate("es")
jmvtools::i18nCreate("fr")
```

--------------------------------

### Typical jmvtools Development Workflow

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

A step-by-step guide to developing jamovi modules using jmvtools, from installation and setup to module creation, testing, and internationalization.

```r
# Install from CRAN
install.packages('jmvtools')

# Load package
library(jmvtools)

# Configure jamovi location (once)
options(jamovi_home = "/opt/jamovi")

# Check setup
jmvtools::check()

# Create new module
jmvtools::create(path = "mymodule")
# Edit R code: R/myanalysis.R
# Edit UI: jamovi/myanalysis.a.yaml
# Edit results: jamovi/myanalysis.r.yaml

# Test prepare (validates only)
jmvtools::prepare(pkg = "mymodule")

# Install for testing in jamovi
jmvtools::install(pkg = "mymodule")

# After adding more analyses
jmvtools::addAnalysis(name = "mytest2", title = "Second Test")
jmvtools::install(pkg = "mymodule")

# Add translations
jmvtools::i18nCreate(code = "es")
jmvtools::i18nCreate(code = "fr")

# Later, update translations
jmvtools::i18nUpdate(code = "*")
```

--------------------------------

### Prepare Module with Custom Jamovi Installation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/prepare.md

Prepare a jamovi module using a custom jamovi installation path. This is useful if you have jamovi installed in a non-standard location. Specify both the module path and the jamovi home path.

```r
# Prepare with custom jamovi installation
jmvtools::prepare(pkg = "mymodule", home = "/opt/jamovi")
```

--------------------------------

### Install jamovi-compiler

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/README.md

Install the jamovi-compiler globally using npm. Requires Node.js to be installed.

```bash
sudo npm install -g git+https://git@github.com/jamovi/jamovi-compiler.git
```

--------------------------------

### Linux: Install Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

On Linux, `jmvtools::install()` defaults to using the Flatpak installation of jamovi. You can also specify a custom path.

```r
# Defaults to flatpak
jmvtools::install()

# Or specify path
options(jamovi_home = "/opt/jamovi")
jmvtools::install()
```

--------------------------------

### prepare(pkg = ".", home = NULL)

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Prepares and validates a jamovi module without installing it.

```APIDOC
## prepare(pkg = ".", home = NULL)

### Description
Prepare/validate module.

### Method
`prepare(pkg = ".", home = NULL)`

### Parameters
#### Common Parameters
- **pkg** (character) - Optional - Module source directory; defaults to ".".
- **home** (character) - Optional - Path to jamovi installation; defaults to 'flatpak' on Linux.

### Error Conditions
Inherits validation from jamovi-compiler. Returns non-zero exit code on validation failure.

### Return Values
Returns `invisible(NULL)` on success.
```

--------------------------------

### Install jamovi module

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/test/010-works/usage.txt

Installs a jamovi module from the specified path. An optional --home path can be provided to specify the installation directory.

```bash
jmc --install path [--home path]
```

--------------------------------

### Install Module from Specific Path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/install.md

Installs a jamovi module from a specified local directory. Provide the path to the module's source code.

```r
jmvtools::install(pkg = "~/projects/mymodule")
```

--------------------------------

### R install() to jamovi-compiler command

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Translates the R install() function call to its equivalent jamovi-compiler command-line invocation, including debug flag.

```r
install(pkg="mymodule", home="/opt/jamovi", debug=TRUE)
→ node jamovi-compiler/index.js --install "mymodule" \
  --home /opt/jamovi --rpath /path/to/R/bin --debug
```

--------------------------------

### Add analysis with custom jamovi installation path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/addAnalysis.md

Provide a specific path to a jamovi installation using the 'home' parameter. This is useful for testing analyses against particular jamovi versions or installations.

```r
jmvtools::addAnalysis(
  name = "regression",
  title = "Linear Regression",
  home = "/opt/jamovi"
)
```

--------------------------------

### Create a new module with a full path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/create.md

This example demonstrates creating a jamovi module at a specified absolute path. Ensure the parent directory exists before running this command.

```r
jmvtools::create(path = "/home/user/projects/mystats")
```

--------------------------------

### Example Command Arguments Array

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/types.md

Illustrates the construction of arguments passed to system2() for jmvtools commands. This array is dynamically built from function parameters.

```r
c("--install", pkg_path, "--home", home_path, "--debug")
```

--------------------------------

### Add Multi-Language Support

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This example shows how to create translation files for Spanish and French, send them for translation, and then update all language files.

```r
jmvtools::i18nCreate("es")
jmvtools::i18nCreate("fr")
# Send po/es/strings.json and po/fr/strings.json to translators
# Get back translations
jmvtools::i18nUpdate("*")  # Update all languages
```

--------------------------------

### Verify jamovi installation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Checks if jamovi is installed and accessible from the R environment. This is useful for ensuring your development setup is correct.

```r
jmvtools::check()
```

```r
jmvtools::check(home = "/opt/jamovi")
```

--------------------------------

### Test Module During Development

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This workflow shows how to install a module for testing, make edits to its files, and then re-install it to see the changes reflected in the jamovi UI.

```r
jmvtools::install("mystats")
# Test in jamovi UI
# Edit files
# Run again to see changes
jmvtools::install("mystats")
```

--------------------------------

### Install jmvtools Package

Source: https://github.com/jamovi/jmvtools/blob/main/README.md

Install the jmvtools package from the jamovi repository using this R command. Ensure you have R installed.

```r
install.packages('jmvtools', repos='https://repo.jamovi.org')
```

--------------------------------

### Prepare jamovi module

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/test/010-works/usage.txt

Prepares a jamovi module for distribution or installation from the specified path. This command often follows the build step.

```bash
jmc --prepare path
```

--------------------------------

### Check Custom Jamovi Installation Path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/check.md

Use this snippet to check a custom jamovi installation path. Provide the absolute path to your jamovi installation as the 'home' parameter.

```r
jmvtools::check(home = "/opt/jamovi")
```

--------------------------------

### Roxygen2 Documentation Example

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/internals.md

Example of roxygen2 comments used for documenting R functions. Running roxygen2::roxygenise() generates man/*.Rd files and updates the NAMESPACE file.

```r
ులDescription here

@param name parameter description
@export
function_name <- function(name) { ... }
```

--------------------------------

### check(home = NULL)

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Verifies the jamovi installation, optionally specifying the jamovi home directory.

```APIDOC
## check(home = NULL)

### Description
Verify jamovi installation.

### Method
`check(home = NULL)`

### Parameters
#### Common Parameters
- **home** (character) - Optional - Path to jamovi installation; defaults to 'flatpak' on Linux.

### Return Values
Returns `invisible(NULL)` on success. Delegates to jamovi-compiler for error handling.
```

--------------------------------

### Install Module in R Script for Testing

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/install.md

Demonstrates installing a module within an R script, including setting debug to FALSE and capturing the output of a system command. This is useful for automated testing or integration into R workflows.

```r
jmvtools::install(pkg = "mymodule", debug = FALSE)
result <- system("echo Installation complete")
```

--------------------------------

### Install Module to Non-Default Jamovi Location

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/install.md

Installs a jamovi module into a jamovi installation located at a path different from the default. Specify the target installation path using the 'home' parameter.

```r
jmvtools::install(
  pkg = "mymodule", 
  home = "/opt/jamovi"
)
```

--------------------------------

### Check jamovi installation

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/test/010-works/usage.txt

Checks the jamovi installation. An optional --home path can be provided to specify the jamovi home directory to check.

```bash
jmc --check        [--home path]
```

--------------------------------

### Install Module with Debug Output

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/install.md

Installs a jamovi module and enables verbose output from the jamovi-compiler by setting the debug parameter to TRUE. This is useful for troubleshooting build issues.

```r
jmvtools::install(pkg = "mymodule", debug = TRUE)
```

--------------------------------

### Install Module in Current Directory

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/install.md

Installs the jamovi module located in the current working directory. This is the default behavior when no package path is specified.

```r
jmvtools::install()
```

--------------------------------

### Prepare module for testing

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Validates a jamovi module's structure and content without installing it. This is a quick check before a full installation.

```r
jmvtools::prepare(pkg = "mymodule")
```

--------------------------------

### Example Extra Arguments for System Calls

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/types.md

Shows optional arguments that can be appended to system calls based on user-defined parameters. These include flags for home directory, R path, and debugging.

```r
# --home flag and value
# --rpath flag and value (non-Windows)
# --debug flag
# --verbose flag
```

--------------------------------

### Check and Install jmvtools Module Conditionally

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

First, run `jmvtools::check()`. If the previous command returns a status code of 0 (indicating success), then proceed to `jmvtools::install()`.

```r
jmvtools::check()
if (system("", intern=TRUE) == 0) {  # Check previous command
    jmvtools::install()
}
```

--------------------------------

### Create Spanish Translation Files

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/i18nCreate.md

Generates translation files for Spanish in the current module directory. This is a basic usage example.

```r
# Create Spanish translation files
jmvtools::i18nCreate(code = "es")
```

--------------------------------

### Set jamovi Installation Location

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Configure the jamovi installation path for jmvtools. This can be set temporarily or persistently in .Rprofile.

```r
# Set jamovi installation location
options(jamovi_home = "/path/to/jamovi")

# In .Rprofile for persistent configuration
# options(jamovi_home = "/opt/jamovi")
```

--------------------------------

### Check Jamovi Installation on Windows with Spaces

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/check.md

On Windows, use this snippet to check a jamovi installation path that contains spaces. The path is automatically quoted by the function.

```r
jmvtools::check(home = "C:\\Program Files\\jamovi")
```

--------------------------------

### Configure Custom jamovi Location

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This shows how to set a custom jamovi installation path using `options(jamovi_home = ...)` either for the current session or permanently in `.Rprofile`.

```r
# Once per session
options(jamovi_home = "/opt/jamovi")

# Or in ~/.Rprofile for permanent config
# Then all functions use that path automatically
jmvtools::install()  # Uses /opt/jamovi
jmvtools::check()    # Uses /opt/jamovi
```

--------------------------------

### Return Values Example

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This shows the visible return value of the `jmvtools::version()` function.

```r
# These return visible values
jmvtools::version()
# [1] "2.7.26"
```

--------------------------------

### Create Brazilian Portuguese Translation Files with Custom Paths

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/i18nCreate.md

Generates translation files for Brazilian Portuguese, specifying both the module package path and the jamovi installation home. This is useful for complex project structures or non-standard jamovi installations.

```r
# Create Brazilian Portuguese translation files
jmvtools::i18nCreate(
  code = "pt_BR",
  pkg = "~/projects/mystats",
  home = "/opt/jamovi"
)
```

--------------------------------

### Setting R Options for jamovi Home

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/configuration.md

Set the jamovi installation path for the current R session or persistently in .Rprofile. Verify the option is set using getOption().

```r
options(jamovi_home = "/opt/jamovi")

# Or set it in .Rprofile for persistent configuration
# Add this line to ~/.Rprofile or project .Rprofile:
# options(jamovi_home = "/path/to/jamovi")

# Verify the option is set
getOption("jamovi_home")
```

--------------------------------

### Windows: Set jamovi Location

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

On Windows, you can specify the jamovi installation path using `options(jamovi_home = ...)`.

```r
# Set jamovi location
options(jamovi_home = "C:/Program Files/jamovi")
```

--------------------------------

### check()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/INDEX.md

Verify that jmvtools can find jamovi installation.

```APIDOC
## check()

### Description
Verify that jmvtools can find jamovi installation.

### Function Signature
`check()`

### Returns
- `invisible(TRUE)`: If jamovi is found. Throws an error otherwise.
```

--------------------------------

### Configure jmvtools Session in R

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/configuration.md

Sets the jamovi installation path for the current R session and demonstrates basic jmvtools commands.

```r
# Configure jmvtools for a session
library(jmvtools)

# Set jamovi installation path
options(jamovi_home = "/opt/jamovi")

# Now all subsequent calls use this location
jmvtools::check()  # Uses /opt/jamovi
jmvtools::create(path = "mymodule")
jmvtools::install(pkg = "mymodule")
```

--------------------------------

### Add Multiple Analyses to a Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/README.md

This snippet demonstrates how to add multiple analyses to an existing jamovi module. After adding analyses, implement each one and then install the module.

```r
jmvtools::addAnalysis("analysis1", "Analysis 1")
jmvtools::addAnalysis("analysis2", "Analysis 2")
# Implement each analysis
jmvtools::install("mymodule")
```

--------------------------------

### jmvtools System Architecture Overview

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Illustrates the relationship between the jmvtools R package, the jamovi-compiler Node.js tool, and the jamovi installation. The R package calls the Node.js compiler via system commands.

```text
┌─────────────────────────────────────────────────┐
│           jmvtools R Package                    │
│  ┌──────────────────────────────────────────┐  │
│  │  R Functions:                            │  │
│  │  - version()                             │  │
│  │  - check()                               │  │
│  │  - create()                              │  │
│  │  - install()                             │  │
│  │  - prepare()                             │  │
│  │  - addAnalysis()                         │  │
│  │  - i18nCreate()                          │  │
│  │  - i18nUpdate()                          │  │
│  └──────────────────────────────────────────┘  │
│                      │                          │
│                      ▼                          │
│  ┌──────────────────────────────────────────┐  │
│  │  system2() calls to Node.js              │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────┐
│      jamovi-compiler (Node.js)                  │
│      inst/node_modules/jamovi-compiler/         │
│  - Validates YAML structures                    │
│  - Compiles R code                              │
│  - Generates module packages                    │
│  - Manages translations                         │
└─────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────┐
│      jamovi Installation                        │
│      (Via --home parameter)                     │
└─────────────────────────────────────────────────┘
```

--------------------------------

### Analysis Definition YAML

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Example of an analysis definition file (`.a.yaml`) for jmvtools. Defines module name, title, group, version, and options.

```yaml
name: mytest
title: My Test
menuGroup: mymodule
version: '1.0.0'
jas: '1.2'
options:
  - name: data
    type: Data
# ... more options
```

--------------------------------

### Create a jamovi Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/README.md

Use this snippet to initiate the creation of a new jamovi module. After creation, you will edit R code and YAML files, then install the module to test it in jamovi.

```r
jmvtools::create("mymodule")
# Edit R code, YAML files
jmvtools::install("mymodule")
# Test in jamovi, iterate
```

--------------------------------

### Results Schema YAML

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Example of a results schema file (`.r.yaml`) for jmvtools. Defines the structure for results, including items like preformatted text.

```yaml
name: results
jrs: '1.1'
items:
  - name: text
    title: Results
    type: Preformatted
# ... more items
```

--------------------------------

### Enable Debug Mode for jmvtools Install and i18n Update

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Enable debug mode for `jmvtools::install()` and `jmvtools::i18nUpdate()` by setting the `debug` argument to `TRUE` for more verbose output.

```r
# Enable debug mode
jmvtools::install(debug = TRUE)
jmvtools::i18nUpdate(debug = TRUE)
```

--------------------------------

### prepare()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/INDEX.md

Prepare a jamovi source module for distribution.

```APIDOC
## prepare()

### Description
Prepare a jamovi source module for distribution.

### Function Signature
`prepare(path)`

### Parameters
#### Path Parameters
- **path** (character) - Required - The path to the jamovi module source directory.
```

--------------------------------

### Get jmvtools Version

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/types.md

Retrieves the installed version of the jmvtools package. The result is a character string and is visible in the console.

```r
result <- jmvtools::version()
# result is "2.7.26" (character)
```

--------------------------------

### Create Initial Translation Files

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Use `i18nCreate` to generate the initial `strings.json` files for a specific language within the `po/{lang}/` directory. This is the first step in setting up translations for your module.

```r
jmvtools::i18nCreate(code = "es")
```

```r
jmvtools::i18nCreate(code = "fr")
```

--------------------------------

### create()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/INDEX.md

Create a new empty jamovi module.

```APIDOC
## create()

### Description
Create a new empty jamovi module.

### Function Signature
`create(name)`

### Parameters
#### Path Parameters
- **name** (character) - Required - The name of the new jamovi module. Module names must be 2+ characters consisting only of letters and digits.
```

--------------------------------

### create(path = ".", home = NULL, gitignore = TRUE)

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Creates a new jamovi module in the specified path, with options to set the jamovi home and include a .gitignore file.

```APIDOC
## create(path = ".", home = NULL, gitignore = TRUE)

### Description
Create new module.

### Method
`create(path = ".", home = NULL, gitignore = TRUE)`

### Parameters
#### Common Parameters
- **path** (character) - Optional - Directory/location for operation; defaults to ".".
- **home** (character) - Optional - Path to jamovi installation; defaults to 'flatpak' on Linux.
- **gitignore** (logical) - Optional - Create .gitignore file; defaults to TRUE.

### Error Conditions
- **"Parent directory '...' does not exist"** - Parent of path doesn't exist
- **"Directory already exists and is not empty"** - Target dir has files
- **"Module names must be at least two characters long and consist only of letters and numbers"** - Invalid name

### Return Values
Returns `invisible(NULL)` on success.
```

--------------------------------

### create()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/create.md

Creates a new jamovi module directory structure with minimal boilerplate. The created module is equivalent to an empty R package with additional jamovi-specific directories. After creation, the module is automatically prepared using prepare().

```APIDOC
## create()

### Description
Creates a new jamovi module directory structure with minimal boilerplate. The created module is equivalent to an empty R package with additional jamovi-specific directories. After creation, the module is automatically prepared using `prepare()`.

### Signature
```r
create(path = ".", home = NULL, gitignore = TRUE)
```

### Parameters
#### Path Parameters
- **path** (character) - Optional - Directory path where the new module will be created. The module name is inferred from the final path component. Must be at least 2 characters, containing only letters and digits.
- **home** (character) - Optional - Path to a local jamovi installation (passed to `prepare()`). If NULL, uses the `jamovi_home` R option or defaults to `'flatpak'` on Linux.
- **gitignore** (logical) - Optional - If TRUE, creates a .gitignore file in the new module directory.

### Returns
**Type:** `invisible(NULL)`
Invisibly returns NULL. The function is called for its side effect of creating the directory structure and files.

### Errors
- **Error:** "Parent directory '...' does not exist" - The parent directory of the path does not exist; it must be created first.
- **Error:** "Directory already exists and is not empty" - The target directory exists and contains files.
- **Error:** "Module names must be at least two characters long and consist only of letters and numbers" - The module name derived from the path is invalid.

### Examples
```r
# Create a new module named "mymodule" in the current directory
jmvtools::create(path = "mymodule")

# Create with a full path
jmvtools::create(path = "/home/user/projects/mystats")

# Create without git ignore file
jmvtools::create(path = "testmodule", gitignore = FALSE)

# Create with custom jamovi installation
jmvtools::create(path = "mymodule", home = "/opt/jamovi")
```

### Created Structure
The function creates the following directory structure:
```
module_name/
├── R/
├── jamovi/
├── DESCRIPTION
├── NAMESPACE
└── .gitignore (if gitignore=TRUE)
```

### Validation Rules
- Module names must start with a letter
- Module names must be at least 2 characters long
- Module names may only contain letters and digits
- Path's parent directory must already exist
```

--------------------------------

### Prepare Module from Specific Path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/prepare.md

Prepare a jamovi module located at a specific file path. Specify the path to the module's source code using the 'pkg' argument.

```r
# Prepare a module from a specific path
jmvtools::prepare(pkg = "~/projects/mymodule")
```

--------------------------------

### Prepare Module in Current Directory

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/prepare.md

Use this snippet to prepare the jamovi module located in the current working directory. No additional parameters are required.

```r
# Prepare the module in the current directory
jmvtools::prepare()
```

--------------------------------

### Accessing R Documentation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Demonstrates how to access help documentation for jmvtools functions within an R session.

```r
?jmvtools::version
?jmvtools::check
?jmvtools::create
# etc.

help(version) # after library(jmvtools)
?jmvtools::version # for unambiguous reference
help(package='jmvtools') # for package overview
```

--------------------------------

### Get Current jmvtools Version

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/version.md

Retrieves the current version of the jmvtools package. The version is read from the DESCRIPTION file.

```r
# Get the current jmvtools version
current_version <- jmvtools::version()
print(current_version)
# [1] "2.7.26"
```

--------------------------------

### i18nCreate()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/INDEX.md

Create translation files for a module.

```APIDOC
## i18nCreate()

### Description
Create translation files for a module.

### Function Signature
`i18nCreate(path)`

### Parameters
#### Path Parameters
- **path** (character) - Required - The path to the jamovi module source directory.
```

--------------------------------

### Prepare Module in Build Script

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/prepare.md

This snippet shows how to prepare a jamovi module within a build script. After execution, the module is ready for packaging or distribution.

```r
# Prepare in a build script
jmvtools::prepare(pkg = "mymodule")
# Module is now ready for packaging or distribution
```

--------------------------------

### Create a new module named 'mymodule' in the current directory

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/create.md

This is the most basic usage of the `create()` function. It initializes a new jamovi module named 'mymodule' in the current working directory.

```r
jmvtools::create(path = "mymodule")
```

--------------------------------

### i18nCreate(code, pkg = ".", home = NULL)

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Creates translation files for a jamovi module in a specified language.

```APIDOC
## i18nCreate(code, pkg = ".", home = NULL)

### Description
Create translation files.

### Method
`i18nCreate(code, pkg = ".", home = NULL)`

### Parameters
#### Path Parameters
- **code** (character) - Required - The language code for the translation files (e.g., "es").

#### Common Parameters
- **pkg** (character) - Optional - Module source directory; defaults to ".".
- **home** (character) - Optional - Path to jamovi installation; defaults to 'flatpak' on Linux.

### Error Conditions
Inherits from jamovi-compiler.

### Return Values
Returns `invisible(NULL)` on success.
```

--------------------------------

### Handle visible and invisible return values

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Demonstrates how to capture visible return values, such as version strings, and how functions with side effects typically return NULL invisibly.

```r
# Visible return - can be stored/used
v <- jmvtools::version()
# [1] "2.7.26"

# Invisible return - used for side effects only
jmvtools::create(path = "mymodule")
# Creates files and directories, returns NULL invisibly
```

--------------------------------

### Module/Analysis Name Validation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Module and analysis names must start with a letter and can contain letters and numbers. They cannot be too short or contain hyphens.

```regex
^[a-zA-Z][a-zA-Z0-9]+$
```

--------------------------------

### R create() to jamovi-compiler command

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Translates the R create() function call to its equivalent jamovi-compiler command-line invocation, including filesystem operations.

```r
create(path="mymodule", home=NULL)
→ (filesystem operations)
→ node jamovi-compiler/index.js --prepare "mymodule" --rpath /path/to/R/bin
```

--------------------------------

### Create a new module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Use this function to initialize a new jamovi module. It creates the necessary directory structure and an optional .gitignore file.

```r
jmvtools::create(path = "mymodule", gitignore = TRUE)
```

--------------------------------

### Build jamovi module

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/test/010-works/usage.txt

Builds a jamovi module from the specified path. This is typically the first step in the module development process.

```bash
jmc --build path
```

--------------------------------

### Configure jamovi Home Directory Persistently

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Set the `jamovi_home` option in `~/.Rprofile` or `.Rprofile` to a specific directory. This ensures the setting is available in every R session.

```r
# ~/.Rprofile
if (require("jmvtools")) {
    options(jamovi_home = "/opt/jamovi")
}

# Then in every session, it's available
jmvtools::install()  # Automatically uses /opt/jamovi
```

--------------------------------

### Calling jamovi-compiler Pattern

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/internals.md

The standard pattern for invoking the jamovi-compiler from R functions. It involves getting the Node.js executable, the compiler path, building arguments, and executing via system2().

```r
exe <- node()                    # Get Node.js executable
jmc <- jmcPath()                # Get compiler path
args <- c(jmc, command, ...)    # Build arguments
system2(exe, args, wait=TRUE)   # Execute
```

--------------------------------

### R-level validation for create()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Illustrates R-level validation checks performed by the create() function, including error messages for invalid module names, non-existent parent directories, and occupied directories.

```r
create(path="mymodule")
  │
  ├─ Check module name matches pattern
  │  └─ Error: "must be at least two characters..."
  │
  ├─ Check parent directory exists
  │  └─ Error: "Parent directory does not exist"
  │
  └─ Check directory not already occupied
     └─ Error: "Directory already exists and is not empty"
```

--------------------------------

### File Structure After Module Creation

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This illustrates the typical file and directory structure created by `jmvtools::create()` for a new jamovi module.

```text
Module created with create("mymodule"):

mymodule/
├── R/                          # R implementation files
├── jamovi/                     # Configuration files
│   ├── myanalysis.a.yaml       # Analysis UI definition
│   └── myanalysis.r.yaml       # Results schema
├── DESCRIPTION                 # Package metadata
├── NAMESPACE                   # Exported symbols
└── .gitignore

After i18nCreate():
├── po/
│   ├── es/
│   │   └── strings.json
│   └── fr/
│       └── strings.json
```

--------------------------------

### Template DESCRIPTION File for Jamovi Modules

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/configuration.md

This template is used by the create() function to generate a standard R package DESCRIPTION file for jamovi modules. The $NAME placeholder is replaced with the module name.

```text
Package: $NAME
Type: Package
Title: What the Package Does (Title Case)
Version: 0.0.0
Author: Who wrote it
Maintainer: The package maintainer <yourself@somewhere.net>
Description: More about what it does (maybe more than one line)
    Use four spaces when indenting paragraphs within the Description.
License: What license is it under?
Encoding: UTF-8
LazyData: true
Imports: jmvcore (>= 0.8.5), R6
```

--------------------------------

### Update Translations with Debug Output

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/i18nUpdate.md

Set 'debug = TRUE' to enable verbose output from the jamovi-compiler, which is useful for diagnosing issues during the translation update process. This example updates French translations for 'mymodule'.

```r
jmvtools::i18nUpdate(
  code = "fr",
  pkg = "mymodule",
  debug = TRUE
)
```

--------------------------------

### Construct Jamovi Compiler Path

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/internals.md

Returns the quoted path to the jamovi-compiler's index.js file. The path is quoted to handle potential spaces in R installation directories. This function is used internally by several jmvtools functions.

```r
jmcPath <- function() {
    paste0('"', system.file('node_modules', 'jamovi-compiler', 'index.js', package='jmvtools'), '"')
}
```

--------------------------------

### Build Jamovi Compiler Arguments

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/internals.md

Constructs command-line arguments for the jamovi-compiler. It handles platform-specific path quoting (Windows) and adds flags like --home, --rpath, and --debug based on provided parameters or environment options. Use this to prepare arguments for system2() calls.

```r
extraArgs <- function(home=NULL, rhome=NULL, debug=FALSE) {
    args <- character()
    
    # Get default home if not provided
    if (is.null(home))
        home <- getOption('jamovi_home')
    
    # Default to flatpak on Linux
    if (is.null(home) && isLinux())
        home <- 'flatpak'
    
    # Quote paths on Windows
    if ( ! is.null(home) && isWindows())
        home <- paste0('"', home, '"')
    
    # Add --home flag if specified
    if ( ! is.null(home))
        args <- c(args, '--home', home)
    
    # Add --rpath on non-Windows platforms
    if ( ! isWindows() && ! is.null(rhome))
        args <- c(args, '--rpath', rhome)
    
    # Add --debug flag if requested
    if (debug)
        args <- c(args, '--debug')
    
    args
}
```

```r
extraArgs(home="/opt/jamovi", debug=TRUE)
# Returns: c("--home", "/opt/jamovi", "--debug")

extraArgs(home="C:\\jamovi", debug=FALSE)  # Windows
# Returns: c("--home", "\"C:\\jamovi\"" )
```

--------------------------------

### Prepare jmvtools Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Use `prepare()` to prepare a jmvtools module. This function is used for side effects and returns invisible(NULL).

```r
jmvtools::prepare()
```

--------------------------------

### Batch Create Multiple jmvtools Modules

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Iterate through a character vector of module names and use `jmvtools::create()` for each to batch create modules.

```r
modules <- c("module1", "module2", "module3")
for (m in modules) {
    jmvtools::create(m)
}
```

--------------------------------

### Run jamovi-compiler in current directory

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/README.md

Invoke the jamovi-compiler from the command line in the target R package directory.

```bash
jmc
```

--------------------------------

### Compiler-level validation during prepare()

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Outlines the validation steps performed by jamovi-compiler during the prepare() process, including YAML syntax, schema compliance, R code compilation, and required fields.

```r
prepare()
  │
  └─ jamovi-compiler validates:
     │
     ├─ YAML syntax
     ├─ Schema compliance
     ├─ R code compilation
     ├─ Required fields
     └─ (Returns error via system2)
```

--------------------------------

### Create a new module without a .gitignore file

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/create.md

Use this option when you do not want a `.gitignore` file to be automatically created in the new module's directory. This can be useful if you are using a different version control system or no version control.

```r
jmvtools::create(path = "testmodule", gitignore = FALSE)
```

--------------------------------

### Create translation files

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/EXPORTED_API.md

Generates initial translation files for a specified language code within a jamovi module. This is the first step in internationalization.

```r
jmvtools::i18nCreate(code = "es", pkg = "mymodule")
```

--------------------------------

### Add Multi-Language Support to a Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/README.md

Use this to create translation files for different languages and update them. After sending translation files to translators and receiving them back, update the module's language support.

```r
jmvtools::i18nCreate("es")
jmvtools::i18nCreate("fr")
# Send translation files to translators
# Receive translations back
jmvtools::i18nUpdate("*")
```

--------------------------------

### R i18nCreate() to jamovi-compiler command

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/architecture.md

Translates the R i18nCreate() function call to its equivalent jamovi-compiler command-line invocation for internationalization.

```r
i18nCreate(code="es", pkg="mymodule")
→ node jamovi-compiler/index.js --i18n "mymodule" --create es
```

--------------------------------

### Create Translation Files for Multiple Languages

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/i18nCreate.md

Iterates through a list of language codes to create translation files for each specified language in a given module. This is efficient for modules supporting multiple languages.

```r
# Create translations for multiple languages
languages <- c("es", "fr", "de", "ja")
for (lang in languages) {
  jmvtools::i18nCreate(code = lang, pkg = "mymodule")
}
```

--------------------------------

### Run jamovi-compiler for a specific package directory

Source: https://github.com/jamovi/jmvtools/blob/main/inst/node_modules/jamovi-compiler/README.md

Invoke the jamovi-compiler specifying the path to the target R package.

```bash
jmc /path/to/package
```

--------------------------------

### Create i18n Files for jmvtools Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

Use `i18nCreate()` to create internationalization (i18n) files for a jmvtools module. This function is used for side effects and returns invisible(NULL).

```r
jmvtools::i18nCreate()
```

--------------------------------

### Add Another Analysis to a Module

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/QUICK_REFERENCE.md

This snippet illustrates how to add a second analysis to an existing module, implement its R code, edit YAML files, and then re-install the module.

```r
jmvtools::addAnalysis("analysis2", "Analysis 2")
# Implement R code
# Edit YAML files
jmvtools::install("mystats")
```

--------------------------------

### i18nCreate() Function

Source: https://github.com/jamovi/jmvtools/blob/main/_autodocs/api-reference/i18nCreate.md

Creates translation files for a specific language in a jamovi module. This function is used to initialize the translation process for a module.

```APIDOC
## i18nCreate()

### Description
Creates translation files for a specific language in a jamovi module. It delegates to the jamovi-compiler tool which extracts translatable strings from the module and creates a template translation file for the specified language code.

### Method
`i18nCreate(code, pkg = ".", home = NULL)`

### Parameters
#### Path Parameters
- **code** (character) - Required - Language code for the translation (e.g., "es" for Spanish, "fr" for French, "pt_BR" for Brazilian Portuguese)
- **pkg** (character) - Optional - Path to a local directory containing the jamovi module source code. Defaults to ".".
- **home** (character) - Optional - Path to a local jamovi installation. If NULL, uses the `jamovi_home` R option or defaults to `'flatpak'` on Linux.

### Returns
**Type:** `invisible(NULL)`

Invisibly returns NULL. The function is called for its side effect of creating translation files.

### Examples
```r
# Create Spanish translation files
jmvtools::i18nCreate(code = "es")

# Create French translation files
jmvtools::i18nCreate(code = "fr", pkg = "mymodule")

# Create Brazilian Portuguese translation files
jmvtools::i18nCreate(
  code = "pt_BR",
  pkg = "~/projects/mystats",
  home = "/opt/jamovi"
)

# Create translations for multiple languages
languages <- c("es", "fr", "de", "ja")
for (lang in languages) {
  jmvtools::i18nCreate(code = lang, pkg = "mymodule")
}
```

### Platform-Specific Behavior
- **Windows:** Paths are automatically quoted to handle spaces
- **Linux:** Defaults to `'flatpak'` if no explicit home is provided
- **macOS:** Uses explicitly provided home parameter

### Translation Files Generated
The jamovi-compiler creates translation files in a `po/` directory structure:
- `po/{language_code}/` - Directory for the language
- `po/{language_code}/strings.json` - Translation template or translation file

The exact structure depends on the module's configuration and the jamovi-compiler version.

### Language Code Format
Language codes should follow standard ISO 639-1 format with optional region:
- Two-letter language codes: "es" (Spanish), "fr" (French), "de" (German), "ja" (Japanese), "pt" (Portuguese)
- With region: "pt_BR" (Brazilian Portuguese), "zh_CN" (Simplified Chinese), "zh_TW" (Traditional Chinese)

### Related Functions
- [`i18nUpdate()`](i18nUpdate.md) - Update existing translation files
```