Package 'tgver'

Internal helper function to run a 'plumber' instance on specific host and port.

Description

Internal helper function to run a 'plumber' instance on specific host and port.

Usage

background_run(server, port = 8000, host = "127.0.0.1")

Arguments

server	an instance of 'plumber' class
port	numeric port to pass to 'server' instance
host	character host value for 'server' instance

---

Internal helper function to: 1. copy the bundled zip 2. unzip 3. cleanup as required. TODO: return a value?

Description

Internal helper function to: 1. copy the bundled zip 2. unzip 3. cleanup as required. TODO: return a value?

Usage

copy_tgve(path, over.write = TRUE)

Arguments

path	character path of TGVE instance
over.write	boolean whether to cleanup the instance in 'path'

---

A function to read and serve at least one file from a directory.

Description

Current version only tries to: Find two files, one .csv and the other .geojson and pass them to TGVE as 'defaultURL' and 'geographyURL' respectively. It will also look at their column names and try to find matching columns. If there is one file, it passes it to 'explore_file' function.

Usage

explore_dir(path, background = FALSE)

Arguments

path	character of a data directory.
background	logical value whether to run instance in 'callr'.

Value

no value returned, depending on 'background' either a or not blocking 'plumber::pr' instance is started. A message is displayed with instance details.

Examples

{
p = file.path(tempdir(), "data")
dir.create(p)
gURL = paste0("https://raw.githubusercontent.com/saferactive/",
"tgve/main/pf-only-name.geojson")
dURL = "https://raw.githubusercontent.com/saferactive/tgve/main/ksi-pf.csv"
download.file(gURL, destfile = file.path(p, "pf.geojson"))
download.file(dURL, destfile = file.path(p, "data.csv"))

ps = explore_dir(p, background = TRUE)
ps$kill()
unlink(p, recursive = TRUE)
}

---

A function to explore a spatial csv or geojson file

Description

Current version can only read geojson/csv files using the given 'file.uri'.

Usage

explore_file(file.uri, background = FALSE)

Arguments

file.uri	character path of file to explore
background	Boolean to run the process in the background, defaults to 'FALSE'

Value

no value returned, depending on 'background' either a or not blocking 'plumber' instance is started. A message is displayed with instance details.

Examples

{
fp = file.path(tempdir(), "test.geojson")
gj = c(
'[
      {"type":"Point","coordinates":[0,0]},
      {"type":"LineString","coordinates":[[-1,-1],[1,1]]},
        {
      "type": "FeatureCollection",
      "features": [
      {
        "type": "Feature",
        "properties": {"id":1},
        "geometry": {"type": "Point", "coordinates": [100.0, 0.0]}
      }
    ]
  }
    ]'
)
write(gj, fp)
ps = tgver::explore_file(fp, background = TRUE)
ps$kill()
unlink(fp, recursive = TRUE)
}

---

Explore an sf R object using TGVE npm package.

Description

Explore an sf R object using TGVE npm package.

Usage

explore_sf(
  sf = NULL,
  background = FALSE,
  static = FALSE,
  path = tempInstance()
)

Arguments

sf	a valid sf object that can be converted to geojson
background	Boolean to decide whether plumber
static	boolean to decide whether data is written to disk and self contained application is built
path	path of a TGVE instance, defaults to one in 'tempdir()' should run in the background

Value

depending on 'background' either a or not blocking 'plumber::pr' object is started or returned. In the case of a 'backgruond' FALSE value a message is displayed with object details.

Examples

{
gj = c(
'[
      {"type":"Point","coordinates":[0,0]},
      {"type":"LineString","coordinates":[[-1,-1],[1,1]]},
        {
      "type": "FeatureCollection",
      "features": [
      {
        "type": "Feature",
        "properties": {"id":1},
        "geometry": {"type": "Point", "coordinates": [100.0, 0.0]}
      }
    ]
  }
    ]'
)
sf = geojsonsf::geojson_sf(gj)
ps = tgver::explore_sf(sf, background = TRUE)
ps$kill()
}

---

Function to replace patterns in given files.

Description

Function to replace patterns in given files.

Usage

file_replace(files = NULL, pattern, replacement)

Arguments

files	character vector of full paths where pattern to be replaced.
pattern	character pattern to replace using 'gsub'.
replacement	character to replace pattern with using 'gsub'.

---

Helper function to generate URLs

Description

The function can generate a URL based on a base URL and as many as TGVE API variables provided to the function.

Usage

get_url(base = "http://127.0.0.1:8000", ...)

Arguments

base	character URL defaults to 'http://127.0.0.1:8000'
...	any or all of the TGVE API variables to replace/add values to.

Value

character URL generated from 'base' and 'tgver::'

Examples

{
url = get_url(dark="false")
url == "http://127.0.0.1:8000?dark=false"
url
url = get_url()
url
}

---

Function to explore available API variables, their types and examples of using them in the TGVE

Description

Function to explore available API variables, their types and examples of using them in the TGVE

Usage

help()

Value

no object is returned

Examples

{
help()
}

---

Good enough regex to sanitize URLs

Description

The task of checking a URL is "hard", see this by J. Hester: https://cran.r-project.org/web/packages/rex/vignettes/url_parsing.html To avoid having a dependency for now, let us not use "rex" R package. To try and understand the regex please see this gist which includes a breakdown of the regex: https://gist.github.com/dperini/729294

Usage

is_valid_url(string)

Arguments

string

must be valid vector of URLs

---

Function to find what files may contain TGVE API variables for functions like 'file_replace' to consume.

Description

Function to find what files may contain TGVE API variables for functions like 'file_replace' to consume.

Usage

list_api_files(path = NULL)

Arguments

path	where TGVE instance is located.

---

Internal helper function to "browse" a URL.

Description

Internal helper function to "browse" a URL.

Usage

openURL(
  url = NULL,
  host = "127.0.0.1",
  port = 8000,
  browser = FALSE,
  path = "",
  protocol = "http://"
)

Arguments

url	character url, if given and valid other parameters will be ignored.
host	character host to pass to plumber
port	integer port to pass to plumber
browser	Boolean whether to specifically launch a browser
path	character path to TGVE instance
protocol	character protocol, this may change

---

Setup an instance.

Description

This function initializes an instance of TGVE for permanent use compared with what tgve_server which relies on a 'tempdir' based instance. It requires a path.

Usage

setup(path = NULL, create = TRUE)

Arguments

path	Character URI to copy tgve instance in.
create	Boolean to create new directory at path, defaults to 'TRUE'.

Value

no value returned

Examples

{
p = file.path(tempdir(), "tgve")
setup(p)
}

---

copy the inst/tgve to a temp in an R session

Description

copy the inst/tgve to a temp in an R session

Usage

tempInstance()

---

Open static TGVE instance

Description

This is the main and most basic function to run an instance of TGVE without back-end. Compared to tgve_server, this function only uses internal functions to setup an instance then opens the entry HTML file. If a path of an instance is provided it opens it, otherwise creates an instance from a 'tempdir'.

Usage

tgve(
  path = Sys.getenv("TEMP_path_ENV"),
  browse = TRUE,
  remote = FALSE,
  url = "https://tgve.github.io/app/"
)

Arguments

path	character directory of a current instance to browse. Defaults to 'TEMP_PATH_ENV' environment variable.
browse	boolean to decide whether to browse the instance or not.
remote	boolean whether to run a remote instance of TGVE. If TRUE the above 'path' and 'browse' parameters will be ignored. Defaults to 'FALSE'
url	if 'remote' is true, then this will be used as the parameter to pass to internal function 'openURL'. It defaults, for convenience, to 'https://tgve.github.io/app/' instance.

Value

directory of the new instance if 'path' is not provided.

Examples

tgve()
# just get the path of the HTML
p = tgve(browse = FALSE)
file.exists(p)

---

Start a TGVE instance server

Description

The function accepts a 'path' to get a directory containing an instance of TGVE, by default this is done via 'TEMP_DIR_ENV' env variable. If neither is given then the function copies a clean copy of the bundled TGVE version into a temporary directory.

Usage

tgve_server(
  path = Sys.getenv("TEMP_path_ENV"),
  port = 8000,
  host = "127.0.0.1",
  background = FALSE,
  run = TRUE
)

Arguments

path	location of TGVE path to be served by plumber.
port	to serve from.
host	host to pass to plumber default 'http://127.0.0.1' to 'FALSE'.
background	run the R process in the background using 'callr', defaults to 'TRUE'.
run	whether to start the server, defaults to 'TRUE'. If not, then the created server will be returned.

Value

the valude returned depends on: (1) 'run', if it is FALSE then an instance of 'plumber::pr', (2) if 'run' is true and 'background' is TRUE the 'plumber::pr' instance is started and its process is returned, and (3) if 'run' is TRUE and 'background' is FALSE then a message is displayed showing the blocking ‘plumber::pr' instance’s 'path', 'port' and 'host'.

Examples

{
# This will run in the background using `callr`
ps = tgve_server(background = TRUE)
Sys.sleep(2)
ps$kill()
}

---

Version of the tgvejs npm package bundled in 'tgver'

Description

Version of the tgvejs npm package bundled in 'tgver'

Package version included as data

Format

A character vector

Note

This was generated using the script in the 'data' directory ('tgver.R' file).

Author(s)

L Hama [email protected]

Examples

{
tgver::version
}

---