docs: examples of using `env(name)` input

[nick-youngblut]

New feature

process-reference-inputs states the following for env( name ):

Declare an environment variable input. The received value should be a string, and it will be exported to the task environment as an environment variable given by name.

So, at least to me, that means the following is how it would be implemented:

workflow{
    MY_PROC("test_value")
}

process MY_PROC {
    input:
    env MY_ENV_VAR

    output:
    path "test"

    script:
    """
    echo $MY_ENV_VAR && touch test
    """
}

...but that just results in:

ERROR ~ Error executing process > 'MY_PROC'

Caused by:
  No such variable: MY_ENV_VAR -- Check script 'main.nf' at line: 23


Source block:
  """
  echo $MY_ENV_VAR && touch test
  """

It would be helpful to have >=1 example or at least more clarification in the docs on how to use env

[bentsherman]

The process input/output types are documented here with more examples. The reference page is still new and relatively sparse. I haven't decided on what else should be moved into the reference docs vs the main process page which is more of a user guide.

[Romain-B]

As a follow-up, it is currently unclear how to use env(name) with other scripting languages than bash.
I have tried several versions of the following toy example with R, to reach a (hacky) conclusion that works.

workflow {
  R_PROCESS("test")
}

process R_PROCESS {
  publishDir(
    path: "${projectDir}/outputs/",
    mode:"copy",
    pattern: "plot.pdf",
  )
  input:
    env 'TITLE'
  output:
    path('plot.pdf')
  script:
  '''
  #! /usr/bin/env Rscript

  # fetch the variable from shell environment
  TITLE = system("echo $TITLE", intern = T) 

  x <- seq(1:10L)
 
  pdf("plot.pdf", height=4, width=4)
  plot(x, log(x), main = TITLE)
  dev.off()
  '''
}

FWIW, my end goal was to have an Rscript block where I don't need to escape every dollar sign. This requires both the single-quote block and an env('name') variable to input the filepath with data for plotting.

[bentsherman]

The env input declares an environment variable in the shell that runs the task script. So you just need to access the environment var through whatever interface your language provides. In Python that is os.getenv(). In R I think it is Sys.getenv().