mozilla

Revision 236086 of Customization

  • Revision slug: Tools/GCLI/Customization
  • Revision title: Customization
  • Revision id: 236086
  • Created:
  • Creator: joewalker
  • Is current revision? No
  • Comment 119 words added, 78 words removed

Revision Content

The Mozcmd Format

The mozcmd format is a way to store GCLI commands for easy access. It is available to Firefox users by setting the devtools.command.dir to point to a directory containing a number of files with the extension mozcmd.

For example if you set devtools.command.dir to point to C:\mozcmd (on windows or /Users/me/mozcmd on Mac/Unix), then Firefox will read mozcmd files from that directory.

Syntax

The mozcmd file format is based on JSON, but with the ability to insert functions in key places - For example the exec function.

The root of the document is an Array, which contains a number of command objects suitable to be passed to gcli.addCommand().

An Example mozcmd File

The following example is taken from the demo repository.

[
  {
    name: 'hello',
    description: 'Show a message',
    params: [
      {
        name: 'name',
        type: 'string',
        description: 'Who to say hello to',
      }
    ],
    exec: function(args, context) {
      return 'Good evening, ' + args.name;
    }
  }
]

Several commands can be placed in one file, and commands always take their name from the `name` property rather than the name of the file.

Comments are not allowed except inside functions.

When a command is executed, this will be set to that of the parent object, so this.name is the name of the command. If a setup step is required then it should be done on first execution, and any results cached on this.

Types

Out of the box we support:

  • The obvious basic types: string, number, boolean
  • setting, settingValue: i.e. prefs (settingValue is string, number, or boolean depending on the underlying type of the setting)
  • node: A single node on the page referenced by CSS expression
  • resource: A CSS or JavaScript file in the page

We're also working on date and file types, but they're not ready yet. For now you should use string.

Further Documentation

The GCLI project contains several pages of relevant documentation:

Security

The idea is to provide the user with the security that just having a mozcmd file available to Firefox is not a security risk, they need to access the command before any JavaScript is executed.

(Note 'access' does not imply that a command needs to be executed. Commands can provide functions to customize parameters. 'Access' is defined as typing the name of the command on the command line (regardless of whether RETURN is pressed)

The current implementation of mozcmd simply evals the script in a Sandbox. This does not provide the promised level of protection, however Bug 767912 calls for the parser to be upgraded.

Extending the mozcmd Format

This section is about future extensibility, it does not document current functionallity.

GCLI currently has 3 extension points:

  • Commands
  • Types
  • Fields

Of these, currently only Commands are publicly extensible (through gcli.addCommand() and gcli.removeCommand()). It it likely that we will add extension points for Types and Fields in the future. It can be debated whether these extension points should be available to a mozcmd file.

Allowing Types and Fields in mozcmd files is likely to be problematic for a number of reasons:

  • It can introduce dependencies between mozcmd files
  • It makes the security guarantees harder to enforce (what if one type replaces one of the built in types)
  • Types and Fields have a deeper interaction with other parts of GCLI, so it could be hard to do cleanly.

Should we find it necessary to allow registration of Types and Fields in a mozcmd file in the future, we can to introduce a 'class' property which has the following legal values ['command'|'type'|'field'] with the default being 'command'.

For example:

[
  {
    name: 'c1', // 'command' by default
    exec: function() { return 'This is the c1 command'; }
  },
  {
    name: 'c2',
    class: 'command', // make it explicit
    exec: function() { return 'This is the c1 command'; }
  },
  {
    name: 't1',
    class: 'type',
    stringify: function(data) { return '...'; },
    parse: function(str) { return new Conversion(...); }
  }
]

Revision Source

<h2>The Mozcmd Format</h2>
<p>The mozcmd format is a way to store GCLI commands for easy access. It is available to Firefox users by setting the <code>devtools.command.dir</code> to point to a directory containing a number of files with the extension <code>mozcmd</code>.</p>
<p>For example if you set <code>devtools.command.dir</code> to point to <code>C:\mozcmd</code> (on windows or <code>/Users/me/mozcmd</code> on Mac/Unix), then Firefox will read mozcmd files from that directory.</p>
<h2>Syntax</h2>
<p>The mozcmd file format is based on JSON, but with the ability to insert functions in key places - For example the <code>exec</code> function.</p>
<p>The root of the document is an Array, which contains a number of command objects suitable to be passed to <code>gcli.addCommand()</code>.</p>
<h2>An Example mozcmd File</h2>
<p>The following example is taken from <a class="link-https" href="https://github.com/joewalker/mozcmd" title="https://github.com/joewalker/mozcmd">the demo repository</a>.</p>
<pre>[
  {
    name: 'hello',
    description: 'Show a message',
    params: [
      {
        name: 'name',
        type: 'string',
        description: 'Who to say hello to',
      }
    ],
    exec: function(args, context) {
      return 'Good evening, ' + args.name;
    }
  }
]
</pre>
<p>Several commands can be placed in one file, and commands always take their name from the `name` property rather than the name of the file.</p>
<p>Comments are not allowed except inside functions.</p>
<p>When a command is executed, <code>this</code> will be set to that of the parent object, so <code>this.name</code> is the name of the command. If a setup step is required then it should be done on first execution, and any results cached on <code>this</code>.</p>
<h3>Types</h3>
<p>Out of the box we support:</p>
<ul> <li>The obvious basic types: <code>string</code>, <code>number</code>, <code>boolean</code></li> <li><code>setting</code>, <code>settingValue</code>: i.e. prefs (settingValue is string, number, or boolean depending on the underlying type of the setting)</li> <li><code>node</code>: A single node on the page referenced by CSS expression</li> <li><code>resource</code>: A CSS or JavaScript file in the page</li>
</ul>
<p>We're also working on date and file types, but they're not ready yet. For now you should use <code>string</code>.</p>
<h3>Further Documentation</h3>
<p>The GCLI project contains several pages of relevant documentation:</p>
<ul> <li><a class="link-https" href="https://github.com/joewalker/gcli/blob/master/docs/index.md" title="https://github.com/joewalker/gcli/blob/master/docs/index.md">Documentation Index</a></li> <li><a class="link-https" href="https://github.com/joewalker/gcli/blob/master/docs/writing-commands.md" title="https://github.com/joewalker/gcli/blob/master/docs/writing-commands.md">Writing Commands</a></li> <li><a class="link-https" href="https://github.com/joewalker/gcli/blob/master/docs/writing-types.md" title="https://github.com/joewalker/gcli/blob/master/docs/writing-types.md">Writing Types</a></li>
</ul>
<h3>Security</h3>
<p>The idea is to provide the user with the security that just having a mozcmd file available to Firefox is not a security risk, they need to access the command before any JavaScript is executed.</p>
<p>(Note 'access' does not imply that a command needs to be executed. Commands can provide functions to customize parameters. 'Access' is defined as typing the name of the command on the command line (regardless of whether RETURN is pressed)</p>
<p>The current implementation of mozcmd simply evals the script in a Sandbox. This does not provide the promised level of protection, however <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=767912" title="https://bugzilla.mozilla.org/show_bug.cgi?id=767912">Bug 767912</a> calls for the parser to be upgraded.</p>
<h3>Extending the mozcmd Format</h3>
<p>This section is about future extensibility, it does not document current functionallity.<br> <br> GCLI currently has 3 extension points:</p>
<ul> <li>Commands</li> <li>Types</li> <li>Fields</li>
</ul>
<p>Of these, currently only Commands are publicly extensible (through <code>gcli.addCommand()</code> and <code>gcli.removeCommand()</code>). It it likely that we will add extension points for Types and Fields in the future. It can be debated whether these extension points should be available to a mozcmd file.</p>
<p>Allowing Types and Fields in mozcmd files is likely to be problematic for a number of reasons:</p>
<ul> <li>It can introduce dependencies between mozcmd files</li> <li>It makes the security guarantees harder to enforce (what if one type replaces one of the built in types)</li> <li>Types and Fields have a deeper interaction with other parts of GCLI, so it could be hard to do cleanly.</li>
</ul>
<p>Should we find it necessary to allow registration of Types and Fields in a mozcmd file in the future, we can to introduce a 'class' property which has the following legal values ['command'|'type'|'field'] with the default being 'command'.</p>
<p>For example:</p>
<pre>[
  {
    name: 'c1', // 'command' by default
    exec: function() { return 'This is the c1 command'; }
  },
  {
    name: 'c2',
    class: 'command', // make it explicit
    exec: function() { return 'This is the c1 command'; }
  },
  {
    name: 't1',
    class: 'type',
    stringify: function(data) { return '...'; },
    parse: function(str) { return new Conversion(...); }
  }
]
</pre>
Revert to this revision