Files
Shell/docs/syntax/index.html
T
Mrsuperx13 bd4fcf12d4 fixed a couple of typos
changed "come code might go here" to "some code might go here"
2023-03-21 13:20:49 -04:00

279 lines
9.4 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" class="uline"><code>shell.nss</code></a> (or <code>shell.shl</code>
in older installations) is located in the <span class="is-family-monospace">installation directory</span> of
<strong>Shell</strong>, depending on your <a href="/docs/installation.html" class="uline">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" class="uline"><span class="is-family-monospace">static</span></a> and <a
href="dynamic.html" class="uline"><span class="is-family-monospace">dynamic</span></a> items are separated
by blank spaces or on a <a href="#breaking-long-lines" class="uline">separate line</a> and must be placed in
parentheses <code>( )</code>.
</li>
<li>Other configuration files can be imported using the <a href="#import" class="uline"><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="/docs/installation.html" class="uline"><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" class="uline"><span class="is-family-monospace">var{}</span></a> for global
variables. Optional.
</li>
<li>Section <a href="set.html" class="uline"><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" class="uline"><span class="is-family-monospace">default{}</span></a> for
default values, which is now <strong>deprecated</strong>. Please use <a href="set.html"
class="uline"><span class="is-family-monospace">set{}</span></a> for new installations.
</li>
</ul>
</li>
<li>Section <a href="static.html" class="uline"><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" class="uline"><span class="is-family-monospace">dynamic{}</span></a> with
definitions for <strong>new <a href="dynamic.html#menuitem" class="uline"><span class="is-family-monospace">menuitems</span></a></strong>.
Optional.
<ul>
<li>Dynamic <a href="dynamic.html#menuitem" class="uline"><span class="is-family-monospace">menuitems</span></a>
may have one of three types: <a href="dynamic.html#menu" class="uline"><span
class="is-family-monospace">menu</span></a>, <a href="dynamic.html#item" class="uline"><span
class="is-family-monospace">item</span></a>, or <a href="dynamic.html#separator"
class="uline"><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="/docs/expressions/string.html"
class="uline"><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="/docs/expressions/string.html#single-quotes" class="uline"><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 {
// some 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 {
// some 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" class="uline"><span class="is-family-monospace">menu</span> tags</a>
</li>
</ul>