Differences between revisions 2 and 3
Revision 2 as of 2008-03-08 13:23:24
Size: 4095
Editor: scott
Comment:
Revision 3 as of 2011-08-26 04:10:17
Size: 4095
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

Summary

This specification proposes that certain configuration stanzas in the job definition may have references to variables in the job environment expanded and replaced with their values before being used.

Rationale

Now that jobs have a stable environment while active, we can use this environment for more than the processes run under Upstart.

Use cases

  • Jobs should be able to running while a particular device is plugged in. Since the device name is often given as an argument to the events, the arguments to the start and stop events need to be matched.

Scope

This scope of this specification is limited to the expansion of event variables within the context of other stanzas, no changes in the collection of those events is given. Should future specifications alter the way event variables are passed to processes, the implementation of this specification should be changed to match.

No new stanzas are specified by this specification.

Design

Expansion Details

  • Variables are directly expanded from the instance environment.
  • Simple variable references, where no ambiguity exists, are the name of the variable preceeeded by a dollar sign:
    $TTY
    $FOO-bar
    $FOO$BAR
  • Where ambiguity exists, or for clarity, the variable name may be surrounded by braces:
    ${FOO}
    ${FOO}bar
    ${FOO}-bar
    ${FOO}${BAR}
  • The dollar sign on its own is just a dollar sign and is not treated as a variable reference:
    foo$ foo => foo$ foo
  • If ambiguity would cause the dollar sign to be considered a variable reference, empty braces can be used:
    foo${}foo => foo$foo
  • Within braces, a variable may be tested and a default or alternate value substituted depending on whether the variable is or is not unset and/or NULL:
    • To substitute a default value if the variable is unset or NULL:
      ${FOO:-default}
    • To substitute a default value if the variable is unset:
      ${FOO-default}
    • To substitute an alternate value if the variable is not unset or NULL:

      ${FOO:+alternate}
    • To substitute an alternate value if the variable is not unset:

      ${FOO+alternate}
  • If a variable referenced is unset, an error will be occur and any match, etc. will fail. In order to permit an unset value, use the default form above with an empty default:
    ${FOO-}
  • Future expansion allows for shell-like processing:
    ${FOO%pattern}
    ${FOO%%pattern}
    ${FOO#pattern}
    ${FOO##patern}

Stanzas

  • Stanzas that set up a process will not undergo variable expansion, since the variables would come directly from the environment or start command and are thus unsanitised.

  • Stanzas that apply to all instances of a job will not undergo variable expansion, since the expansion will only apply to active instances.

  • Stanzas that are unique to each instance of a job and determine the automatic handling of that job will undergo variable expansion.

  • Currently only one stanza exists that will undergo variable expansion: stop on.

    start on tty-added
    stop on tty-removed $TTY
  • Despite appearances, the script and exec stanzas do not undergo variable expansion. Instead these are passed unmodified to a shell which will expand them itself; thus exec supports far more forms of expansion than stop on.

Implementation

Data preservation and migration

These changes should be backwards compatible with the previous behaviour as variable references are unlikely in the values of event arguments.


ExpandEventVariables (last edited 2011-08-26 04:10:17 by localhost)