update with draft gp tool doc

_quarto.yml

@@ -14,6 +14,7 @@ website:
         text: Home
       - text: Packages
         href: packages.qmd
+      - geoprocessing-tools.qmd
       - tutorials.qmd
       - workflows.qmd
 

geoprocessing-tools.qmd

@@ -0,0 +1,120 @@
+---
+title: "R Geoprocessing tools"
+---
+
+Much like a python geoprocessing (GP) script tool, R based script tools can be created
+allowing you to create GP tools and toolboxes that utilize the power of R. 
+The basic anatomy of an R script GP tool is like so:
+
+```r
+tool_exec <- function(in_params, out_params) {
+  # do things here
+}
+```
+
+
+There _must_ be a function defined named `tool_exec()`. This is what is going
+to be ran by ArcGIS Pro. 
+
+## Input and Output Parameters
+
+Additionally, there must be two arguments that  correspond to input 
+parameters and output parameters. The conventional name of 
+these arguments are `in_params` and `out_params`. The first argument will 
+_always_ refer to the input parameters and the second to the outputs.
+
+`in_params` and `out_params` are named lists. The elements of these lists are
+determined by the **direction** of a parameter. 
+
+![](images/gp-tool-properties.png){width=50%}
+
+If the direction is `Input` it will be contained in `in_params`. Likewise, 
+if the direction is `Output`, it will be contained in `out_params`. 
+
+## Using parameters
+
+We can extract values from the `in_params` and `out_params` lists by the name
+of the parameter. 
+
+:::{.callout-caution}
+The name of the parameter must match that of the **Name** column in the `Parameters` 
+option of the Tool Properties. _It is not_ the Label column.
+:::
+
+For example, if we wanted to parse the `date` parameter we could write our
+function like so: 
+
+```r
+tool_exec <- function(in_params, out_params) {
+  # fetch the date parameter
+  date_str <- in_params[["date"]]
+
+  # parse it using {anytime}
+  clean_date <- anytime::anytime(date_str)
+
+  # ... do additional things
+}
+```
+
+## Parameter types
+
+There are number of different type of parameters that can be provided to a 
+geoprocessing (GP) tool. The type of parameter that is chosen determines how 
+that parameter will appear in the GP pane's UI. Each parameter type can be 
+represented by a basic scalar R type: `integer`, `double`, `character`, `logical`, or 
+`NULL`.
+
+:::{.callout-tip}
+A scalar value is a vector with only a single element. 
+:::
+
+
+It is incumbent upon you to take these parameter inputs and use them appropriately in R.
+
+| Parameter Data Type | R type |
+| --------- | ------ | 
+| String | `character` |
+| Boolean | `logical` |
+| Double | `numeric` |
+| Date | `character` in the format of your system e.g. `"11/17/2023 4:35:57 PM"` |
+| Field | `character` the field name of a feature class |
+| Folder | `character` absolute path e.g. `"C:\\Users\username\Documents"` |
+| Feature Class | `character`absolute path e.g. `"C:\\Users\username\mydatabase.gdb\\feature_class` |
+| Spatial Reference | `character` a string representation of the spatial reference e.g. `"PROJCS["...."]"` |
+
+: Data type mapping {.striped tbl-colwidths="[25,75]"}
+
+### Multiple Values
+
+When selecting the `Multiple values` check box in the parameter data type UI, users 
+can then provide multiple inputs of that type. 
+
+![](images/gp-parameter-type.png)
+
+When this is done, each of the input values will be contained inside of a list. If you have multiple values ticked for the `String` type, you will get a list of scalar character vectors.
+
+**This is important** so it bears repeating! When users provide multiple values they will
+be captured in R as a list of scalars. Meaning that if you have multiple `String` values 
+you will not get a character vector with a length greater than one. 
+
+Take the below input for example
+
+![](images/gp-multiple-strings.png)
+
+In R we would get the `list("string 1", "string 2")` and **not** `c("string 1", "string 2")`.
+
+:::{.callout-tip}
+To turn a list of scalars of the same type—e.g. double, integer, logical, or character—into a vector you can use `unlist()`. For example `unlist(list("string 1", "string 2"))` will give us `c("string 1", "string 2")`.
+:::
+
+
+## Common Patterns
+
+- Reading a Feature Class
+- Converting it to an sf object
+- Writing a Feature Class
+- Autopopulate field drop-down using dependent parameter
+
+## Dependent Parameters 
+
+- Autopopulate field drop-down using dependent parameter