Differences between revisions 1 and 2
Revision 1 as of 2007-04-26 17:09:00
Size: 2068
Editor: scott
Comment:
Revision 2 as of 2008-03-08 13:23:24
Size: 4095
Editor: scott
Comment:
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
## Copy into the Launchpad entry's summary box.
## Probably says "This specification proposes" somewhere.

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.
Line 11: Line 12:
## Why do we need this feature or why are we removing it?
Now that jobs have a stable environment while active, we can use this environment for more than the processes run under Upstart.
Line 16: Line 19:
## Bullet point list of examples requiring the change.
## DO NOT USE PEOPLE (e.g. "Scott is a ...")
## Use real world examples ("The udev job must be started when...")


## This section may be removed if the reasoning is obvious from the
## rationale, and it's hard to think of a different "use case"
Line 27: Line 23:
No new stanzas are specified by this specification.
Line 29: Line 27:
 * === Expansion Details ===
Line 31: Line 29:
## Normally a bullet-pointed list of design points, with example
## configuration syntax or events.
 * 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`.
Line 34: Line 104:
=== Code ===
## Paragraphs of modifications that must be made.
## Refer to functions and filenames.
Line 38: Line 105:
## Common phrases:
Line 40: Line 106:
These changes should be backwards compatible with the previous behaviour as variable references are unlikely in the values of event arguments.
Line 41: Line 108:
## These changes are backwards compatible with the previous behaviour.


## These changes remove an undocumented feature, so should not affect any existing jobs.
== Unresolved issues ==
## Anything remaining here means the spec can't be approved.

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 2008-03-08 13:23:24 by scott)