Mailing-List: contact dev-help@aurora.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@aurora.incubator.apache.org
MIME-Version: 1.0
Date: Mon, 19 May 2014 11:44:14 -0400
Message-ID: 
 <CAFGkSCksMgW3V_rkHQ7pDN1Lx=LatO92FKqwcp4s9yn2Q8h+8w@mail.gmail.com>
Subject: Adding shorthands, defaults,
 and initialization files to the aurora client
From: Mark Chu-Carroll <mchucarroll@apache.org>
To: dev@aurora.incubator.apache.org
Content-Type: multipart/alternative; boundary=047d7bf17dccabc33904f9c2a231

--047d7bf17dccabc33904f9c2a231
Content-Type: text/plain; charset=UTF-8

Folks:

Now that clientv2 is approaching stability, I'd like to start making some
usability changes. These are completely backwards compatible, but they're
intended to make the most common ways of using the aurora client more
convenient for users, without making any use-cases more difficult.

A proposal for how to do this is below. Comments are not just welcome but
required!

Thanks!

      -Mark

# Shorthands in the Aurora Client

Most of the time, users are doing the same thing, over and over again.
They're working mainly on one particular service, in one particular
workspace. But they need to repeat the same parameters, over and over
again.

To reduce this, we'd like to support a set of mechanisms for creating
shorthands and defaults. In this document, I propose what kinds of
shorthands - both standard, and user customizable - that we can
implement in the aurora client.

## Standard Shortcuts

To save typing, we'll add _automatic_ shorthand generation to
the command-line framework. For nouns and verbs, any unambiguous
prefix of the appropriate word will be automatically expanded to
the full word.

   * `aurora j c` will be expanded to `aurora job create`.
   * `aurora con l` will be expanded to `aurora config list`.

## User Customizations

To allow users to customize shorthands, we'll provide a
builtin capability to allow users to provide a configuration
file, from which their customizations will be loaded.
Many applications use a simple pattern to solve similar problems.
Vagrant uses a file named "Vagrantfile"; when you run vagrant, if you
don't specifically tell the tool where to find a configuration, it looks
in the current directory or one of its parents to find a file named
"Vagrantfile".

We'd like to follow a similar pattern, and create an "AuroraInit" file.

### What goes into an init file?

Defaults and aliases.

A default specifies a set of _bindings_. If a parameter is omitted
from a command, and there's a binding for that parameter, it will be
automatically inserted into the command as if the user had typed it.

An alias is a short equivalent for a parameter. When a command line is
provided by a user, aliases will be expanded inline.  A user can
specifically
mark an alias for expansion by prefixing it with "@"; if an alias
appears on the command-line surrounded by whitespace, it will be
replaced even if it isn't marked with an "@".

For example, an init file could contain the following:

    init=Init(
      defaults={
        "jobspec": "west/markcc/test/myservice",
        "config_file": "./src/aurora/myservice.aurora"
      },
      aliases={
        "east": "east/markcc/test/myservice",
        "c": "east",
        "me": "markchucarroll"
      })


Then, if the user ran "`aurora job create`" without any parameters,
it would automatically be expanded to
"`aurora job create west/markcc/test/myservice
./src/aurora/myservice.aurora`".

If a user ran "`aurora job create east`", the alias `east` would be
expanded to "east/markcc/test/myservice", and the missing config file
parameter would
be instantiated using the default, to create a command-line:
"`aurora job create east/markcc/test/myservice
./src/aurora/myservice.aurora`".

If a user ran "aurora create @c/@me/test/myservice", the two aliases would
be expanded, and the omitted configuration parameter would be added:
"`aurora job create east/markchucarroll/test/myservice
./src/aurora/myservice.aurora`".


### Config Files

The aurora client will look for a configuration file in the following
locations, in order:

   1. A file named "AuroraInit" in the current directory.
   2. A file named "AuroraInit" in the sequence of parent directories of the
     current directory up to the nearest repository root.
   3. A file named ".aurora" in the user's home directory.


Like most other files loaded by the aurora client (job configuration files,
hook files), the init file is a Pystachio configuration. It uses the
following schema:

    class Init(Struct):
      defaults=Map(String, String)
      aliases=Map(String, String)

The configuration defined by an init file is the object of type `Init`
that is assigned to the variable `init` in the init file.

--047d7bf17dccabc33904f9c2a231--