Files
Shell/docs/syntax/index.html
T
2023-03-06 09:19:07 +01:00

288 lines
10 KiB
HTML

<h4>Syntax Rules for Configuration Files</h4>
<br>
<p>This chapter describes the syntax rules for the configuration files.</p>
<p>The main configuration file <a href="#shell.nss"
style="border-bottom: 1px solid currentColor;"><code>shell.nss</code></a> is located in the <span
class="is-family-monospace">installation directory</span> of Shell, depending on your <a
href="../installation.html" style="border-bottom: 1px solid currentColor;">installation method</a>.</p>
<h5 id="syntax-general">General rules</h5>
<ul>
<li>Syntax is case-insensitive.</li>
<li>Spaces around the equal (<code>=</code>) sign are optional and are ignored.</li>
<li>The properties of <a href="static.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">static</span></a> and <a href="dynamic.html"
style="border-bottom: 1px solid currentColor;"><span class="is-family-monospace">dynamic</span></a> items
are separated by blank spaces or on a <a href="#breaking-long-lines"
style="border-bottom: 1px solid currentColor;">separate line</a> and must be
placed in parentheses <code>( )</code>.
</li>
<li>Other configuration files can be imported using the <a href="#import"
style="border-bottom: 1px solid currentColor;"><span class="is-family-monospace">import</span> tag</a>.
</li>
</ul>
<div class="notification is-info is-light">
<i>Tip:</i> When there is an error, it is recorded in the log file (<code>shell.log</code>, which is also located in
your <a href="../installation.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">installation directory</span></a>.).
</div>
<h5 id="shell.nss">shell.nss structure</h5>
<p>The global section <code>shell{}</code> may have the following subsections:</p>
<ul>
<li>Section <a href="variables.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">var{}</span></a> for global variables. Optional.
</li>
<li>Section <a href="set.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">set{}</span></a> for settings. Optional.
<ul>
<li>As of version <code>1.8.0</code>, <span class="is-family-monospace">set{}</span> has replaced the
section <a href="default.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">default{}</span></a> for default values, which is now <strong>deprecated</strong>.
Please use <a href="set.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">set{}</span></a> for new installations.
</li>
</ul>
</li>
<li>Section <a href="static.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">static{}</span></a> with instructions on how to <strong>change existing
menuitems</strong>. Optional.
<ul>
<li>Static items are only of one type: item.</li>
</ul>
</li>
<li>Section <a href="dynamic.html" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">dynamic{}</span></a> with definitions for <strong>new <a
href="dynamic.html#menuitem" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">menuitems</span></a></strong>. Optional.
<ul>
<li>Dynamic <a href="dynamic.html#menuitem" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">menuitems</span></a> may have one of three types: <a
href="dynamic.html#menu" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">menu</span></a>, <a href="dynamic.html#item"
style="border-bottom: 1px solid currentColor;"><span class="is-family-monospace">item</span></a>,
or <a href="dynamic.html#separator" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">separator (sep)</span></a>.
</li>
</ul>
</li>
</ul>
<h5 id="syntax-example">Example</h5>
<pre><code class="lang-shell">shell
{
// global variables
var // variables
{
// variables content
variable-name = variable-value
...
}
set // settings
{
theme
{
set-name = set-value
...
}
set-name = set-value
set-name = [set-value, set-value, ...]
...
}
images
{
id = value
"item 1" = value
id1,id2, id3, "item 2" = value
....
}
// static items
static
{
// static items content
item ( property-name = property-value ... )
...
}
// dynamic items
dynamic
{
// dynamic items content
item ( property-name = property-value ... )
separator [( property-name = property-value ... )]
menu ( property-name = property-value ... )
{
var // local variables
{
variable-name = variable-value
...
}
item ( property-name = property-value ... )
...
}
...
}
}</code></pre>
<br>
<h4 id="breaking-long-lines">Breaking Long Lines</h4>
<p>For best readability, users often like to avoid lines longer than 80 characters. single
quotes also allow break up a line.</p>
<pre><code class="lang-shell">shell
{
dynamic
{
item(title='Command prompt'
cmd='cmd.exe')
}
}</code></pre>
<br>
<h4 id="import"><span class="is-family-monospace">Import</span> tag</h4>
<p>To better organise the configuration file, parts of the configuration can be saved in separate files. These are then
imported using the import tag. With this method, it is also possible to import the same file as a sort of "module"
into different parts of the configuration. A convenient way to include the same sub-menu in different
locations..</p>
<h5 id="import-syntax">Syntax</h5>
<p>The general syntax is as follows:</p>
<pre><code class="lang-shell">shell
{
[ %section% ] import %path%
}</code></pre>
<p>Where</p>
<ul>
<li id="import-syntax-section"><code>%section%</code> is the name of a section. Optional. If given, it must be one
of
<ul>
<li>var</li>
<li>set</li>
<li>images</li>
<li>static</li>
<li>dynamic</li>
</ul>
The section name is written literally, without any quotes (or the percent signs).
</li>
<li id="import-syntax-path"><code>%path%</code> is a <a href="../expressions/string.html"
style="border-bottom: 1px solid currentColor;"><span class="is-family-monospace">string</span></a> literal,
that returns the path to the config file that shall be imported. This can be a relative path to the location of
the file where the <span class="is-family-monospace">import</span> tag is used, or it can be an absolute path.
Expressions are supported when using <a href="../expressions/string.html#single-quotes"
style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">single quotes</span></a>.
</li>
</ul>
<p>There are effectively two different ways this tag is applied, depending on whether the optional
<code>%section%</code> is given:</p>
<ul>
<li>Import an entire section</li>
<li>Import as a partial:</li>
</ul>
<h5 id="import-section">Import an entire section</h5>
<pre><code class="lang-shell">shell
{
// import an entire section
%section% import %path%
}</code></pre>
In this case, the content of the file found at <code>%path%</code> will be imported into <strong>a newly
created</strong> <code>section{}</code>.
The result would then look like so:
<pre><code class="lang-shell">shell
{
// import an entire section
section {
/* content of the imported file goes here! Do not include
*
* section {
* }
*
* in your imported file!
*/
}
}</code></pre>
<p>This syntax may be used only in the following places: </p>
<ul>
<li><s>root section <span class="is-family-monospace">shell{}</span>: <code>shell import %path%</code></s>
</li>
<li>the global sections
<ul>
<li><span class="is-family-monospace">var{}</span>: <code>var import %path%</code></li>
<li><s><span class="is-family-monospace">set{}</span>: <code>set import %path%</code></s></li>
<li><span class="is-family-monospace">images{}</span>: <code>images import %path%</code></li>
<li><s><span class="is-family-monospace">static{}</span>: <code>static import %path%</code></s></li>
<li><s><span class="is-family-monospace">dynamic{}</span>: <code>dynamic import %path%</code></s>
</li>
</ul>
</li>
<li>
sub-sections of the <span class="is-family-monospace">set{}</span> section:
<ul>
<li><s><span class="is-family-monospace">set.theme{}</span>: <code>theme import %path%</code></s>
</li>
<li><s><span class="is-family-monospace">set.theme.background{}</span>: <code>background import
%path%</code></s></li>
<li><s><span class="is-family-monospace">set.theme.item{}</span>: <code>item import
%path%</code></s></li>
<li><s><span class="is-family-monospace">set.theme.border{}</span>: <code>border import
%path%</code></s></li>
<li><s>...</s></li>
<li><s><span class="is-family-monospace">set.tip{}</span>: <code>tip import %path%</code></s></li>
<li><s><span class="is-family-monospace">set.exclude{}</span>: <code>exclude import
%path%</code></s></li>
<li><s><span class="is-family-monospace">set.static{}</span>: <code>static import %path%</code></s>
</li>
<li><s><span class="is-family-monospace">set.dynamic{}</span>: <code>dynamic import
%path%</code></s></li>
</ul>
</li>
</ul>
<h5 id="import-partial">Import as a partial</h5>
<pre><code class="lang-shell">shell
{
section {
// come code might go here. Optional.
// import of a partial section
import %path%
// some more content might go here. Optional.
}
}</code></pre>
In this case, the content of the file found at <code>%path%</code> will be imported into the <strong>already
existing</strong> <code>section{}</code>.
The result would then look like so:
<pre><code class="lang-shell">shell
{
section {
// come code might go here. Optional.
// import of a partial section
/* content of the imported file goes here! Do not include
*
* section {
* }
*
* in your imported file!
*/
// some more content might go here. Optional.
}
}</code></pre>
<p>This syntax may be used nearly anywhere: </p>
<ul>
<li>in any section</li>
<li>in the body of <a href="dynamic.html#menu" style="border-bottom: 1px solid currentColor;"><span
class="is-family-monospace">menu</span> tags</a></li>
</ul>