---
title: "Upgrading STICS XML files"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Upgrading STICS XML files}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  tidy = TRUE
)

```

```{r eval=FALSE}
library(SticsRFiles)
```

```{r include=FALSE}
suppressWarnings(library(SticsRFiles))
```

```{r echo=FALSE}
stics_version <- get_stics_versions_compat()$latest_version
```


The XML files structure has changed between STICS version **9.2** and versions **10.X.Y** and a transformation is mandatory.    

So, to avoid difficulties and errors with manual XML files modifications, functionalities have been developed to do so automatically.

One can either transform a complete workspace directory at once or each kind of file individually.


```{r, include = FALSE, eval=FALSE}
example_data <- SticsRFiles::download_data(out_dir = tempdir(),
                                          example_dirs = "study_case_1", "V9.2")
workspace <- file.path(example_data, "XmlFiles")
out_dir <- file.path(tempdir(), "XmlFiles_V10.0")
if (!dir.exists(out_dir)) dir.create(out_dir)
javastics <-
  "/home/plecharpent/tmp/TEST_UPDATE_XML_V9_V10/JavaSTICS-1.41-stics-9.2"
upgrade_workspace_xml(workspace = workspace, javastics = javastics,
                      out_dir = out_dir, overwrite = TRUE)
```

## Upgrading a whole workspace

In that case, a workspace adapted to the new version is recreated.

So, apart from the XML files, some other files as outputs definition files (*.mod), weather files attached to USMs and also observation files (named with the USM name, \*.obs) are copied to the new workspace.

```{r, eval = FALSE, results='markup'}
workspace <- "/path/to/workspace/dir/V9.2"
out_dir <- "/path/to/out/dir/V10.0"
javastics <- "/path/to/JavaSTICS-1.41-stics-9.2"
upgrade_workspace_xml(workspace = workspace, javastics = javastics,
                      out_dir = out_dir)
```
Here is the output display indicating the treated files:

<pre style="font-size:11px;">
Upgrading files from version V9.2 to V10.0    
From:  /path/to/workspace/dir/V9.2   
To:  /path/to/out/dir/V10.0    
-----------------------------------   
param_gen.xml   
param_new_form.xml   
usms.xml   
sols.xml   
*_sta.xml   
*_ini.xml   
*_tec.xml   
Copying *.mod files.   
Copying *.obs files.   
Copying weather files.   
*_plt.xml    
-----------------------------------   
Files upgrade and copy is complete.   
</pre>



## Upgrading a specific file kind

For each kind of file, a specific function is to be used for upgrading its format.

* **`usms.xml`** : upgrade_usms_xml
* **`*_ini.xml`** files: upgrade_ini_xml
* **`param_gen.xml`**: upgrade_param_gen_xml
* **`param_newform.xml`**: upgrade_param_newform_xml
* **`*_plt.xml`** files: upgrade_plt_xml
* **`sols.xml`**: upgrade_sols_xml
* **`*_sta.xml`** files: upgrade_sta_xml
* **`*_tec.xml`** files: upgrade_tec_xml

The input arguments of these functions may vary, refer to each function help for details
about its use.    

Sometimes, general parameter files are needed as function inputs because of parameters or options codes movement to specific files. 

For example, the **`usms.xml`** file is to be upgraded as follows:

```{r, include = FALSE, eval=FALSE}
usms_path <- file.path(example_data, "XmlFiles", "usms.xml")
out_dir <- file.path(tempdir(), "XmlFiles_V10.0")
param_gen_path <- file.path(javastics, "config", "param_gen.xml")
upgrade_usms_xml(file = usms_path, param_gen_file = param_gen_path,
                 out_dir = out_dir, overwrite = TRUE)
```

```{r, eval = FALSE}
usms_path <- "/path/to/workspace/dir/V9.2/usms.xml"
out_dir <- "/path/to/workspace/dir/V10.0"
param_gen_path <- "/path/to/JavaSTICS-1.41-stics-9.2/config/param_gen.xml"
upgrade_usms_xml(file = usms_path, param_gen_file = param_gen_path,
                 out_dir = out_dir)
```