91 lines
10 KiB
HTML
91 lines
10 KiB
HTML
[!]
|
|
[=title "Usage"]
|
|
[=isSimple true]
|
|
[=content-]
|
|
<div class="text">
|
|
Sitix is a KISS program, so there's not a lot of setup. Once you've got it installed (see <a href="[^baseurl]/pages/install.html">for information on that</a>),
|
|
you need a project to build. The simplest Sitix project structure is just a <code>site</code> folder, which contains the actual Sitix "scripts". When
|
|
(you absolutely must be outside of the site directory to do this!) you run <code>sitix site</code>, Sitix will delete the <code>output</code> directory
|
|
and all contents, if it exists, and then create a new <code>output</code> directory for the compiled site code. Then, Sitix will walk down the tree of
|
|
your <code>site</code> directory, creating appropriate subdirectories and directly copying over any file that doesn't have an opening phrase - <code>\[!]</code>,
|
|
for a Sitix page, or <code>\[?]</code> for a data page (which will not be rendered itself, but may be used for templating or configuration). The opening phrase
|
|
MUST be the first three bytes of the file; if there are any whitespaces before it, the file will be treated as plain data. If you want
|
|
it to render to a different directory, pass the <code>-o location</code> flag.<br><br>
|
|
Configuration can be managed with the <code>-c</code> command line directive, which directly inserts a Sitix object to the virtual root scope. For instance,
|
|
this site uses the <code>-c production</code> argument to enable the production endpoint as opposed to the local development endpoint. It could also be
|
|
something like <code>-c endpoint https://swaous.asuscomm.com/sitix</code>, directly inserting the endpoint.
|
|
</div>
|
|
<div class="note">
|
|
WARNING: <code>-o</code> is very dangerous! If you tell Sitix to render to a directory with important information in it, <b>that directory is as good as gone</b>.
|
|
At the moment Sitix does not put any effort into questioning your choices, so make sure to double-check everything is okay before running any sitix command! Avoiding
|
|
<code>-o</code> unless you <i>really</i> need it is generally a good policy.
|
|
</div>
|
|
<div class="text">
|
|
Let's cover some syntax. All Sitix commands are enclosed in brackets like <code>\[command]</code> (you can escape brackets with backslashes). There aren't very many
|
|
Sitix commands; at the moment, it's just:
|
|
<ul>
|
|
<li><code>\[=variableName variableContent]</code>: This simply sets <code>variableName</code> to be equal to <code>variableContent</code> at that point on the scope tree.</li>
|
|
<li><code>\[=variablename-]variableContent\[/]</code>: The expanded form of above. This allows for much more complicated variables, including variables containing
|
|
Sitix commands (in the compressed form, anything inside MUST be plaintext). It's generally preferred to use this when the content is more than a word or two.</li>
|
|
<li><code>\[^variableName]</code>: "Dereferences" a variable, forcing it to render. If that variable contains other variables (like <code>\[=parent-] \[=child-] content \[/] \[/]</code>),
|
|
the child variables will NOT be rendered, but if variables with the same name as the children exist at some point in the parent tree of the dereferenced variable exist, they will be replaced.
|
|
Variables at the dereferencing position will NOT be replaced.</li>
|
|
<li><code>\[#filename]</code>: Dereferences a Sitix file (or plain file, which would just copy over content without processing it) at this position. The filename must be relative
|
|
to the root directory (usually the <code>site</code> directory), rather than the directory the including file is stored in. This is very useful for templating.</li>
|
|
<li><code>\[i <...>]main section\[e]else section\[/]</code>: This is an if condition. The content of the condition is an Evals directive. If it's truthy, the main section of the
|
|
if statement will be rendered. If it's not truthy, the else section will be rendered. You can put whatever you want in either section. For more information on Evals, see below.</li>
|
|
<li><code>\[f array iterator]</code>: For loop that iterates over an array (note: in Sitix, every subdirectory of the root dir can be treated as
|
|
an array of objects, each object being a file! This allows things like generating blog links). The <code>iterator</code> variable will be, for every item,
|
|
the referenced array element. <b>Note: When iterating over a directory, every file will be given a <code>filename</code> property!</b> This can be used like
|
|
<code>\[f directory i]\[^i.filename]\[/]</code>, which would spew out the filenames of every file in that directory.</li>
|
|
<li><code>\[@command option]</code>: Set a file-specific flag. File-specific flags are used to do things like minify text. For example, the minifier is controlled by
|
|
<code>\[@on minify]</code>, which enables minifier for the file, and <code>\[@off minify]</code>, which disables minifier. Minifier simply reduces chains of whitespace
|
|
to a single whitespace. <code>\[@on markdown]</code> and <code>\[@off markdown]</code> allow Markdown-like processing across the file. Sitix Markdown is not quite ready
|
|
for widespread use, yet, but at the time of writing supports *italic*, **bold**, __underline__, ~~strikethrough~~, `code`, and automatic paragraphs/line breaks.
|
|
It works quite nicely with minifier, yes.</li>
|
|
<li><code>\[>filename]object\[/]</code>: Renders an object into a new file represented by filename. Filename should be a relative path as it will be transmuted into
|
|
the output directory. This is very useful for, say, turning a single Sitix object file containing webcomic post data into a directory full of posts.</li>
|
|
<li><code>\[~object1 object2]</code>: Sets the ghost on object1 to object2, effectively cloning object2 to object1. It is not a true copy; changes in object2 will be
|
|
reflected in object1. However, unlike with normal dereference-setting (<code>\[=object1]\[^object2]\[/]</code>), you can access nested objects inside the ghost.
|
|
It's not unlike changing the value of a pointer in C.</li>
|
|
</ul>
|
|
You can use Sitix commands in any file with a Sitix opening phrase; Sitix commands in files that do not have an opening phrase will be ignored.<br><br>
|
|
There are a number of "special objects" that resolve magically at different places. The most useful two are <code>__after__</code> and <code>__before__</code>,
|
|
which crop up in for loops. They allow you to reference the object that came before or after, like <code>\[^i.__after__]</code>. __this__ is pretty much useless
|
|
except in <i>very</i> niche situations, because of the unclear rules behind it; I will document those on a later date. __file__ is always the root object of the current file,
|
|
- you can most likely guess why that's useful.
|
|
</div>
|
|
<div class="text">
|
|
Evals is a very simple stack-based language meant for evaluating string statements. When data is entered in the Evals program, it's immediately pushed
|
|
to the stack (like <code>"hello"</code>, <code>3.14</code>, <code>true</code>, or <code>some.sitix.variable</code>). At the end of Evals rendering, whatever is left on the stack
|
|
is considered the result (if there is more than one thing on the stack, Evals will give you a Bad Syntax error and return an ErrorObject). To manipulate data,
|
|
there are a number of commands that work on the top of the stack:
|
|
<ul>
|
|
<li><code>equals</code>: Checks if two values on the stack are equal to each other. It will remove both values from the stack and add a boolean value as the result.</li>
|
|
<li><code>not</code>: Pops the top value off the stack and replaces it with a boolean equal to the opposite of the truthyness of that object. <code>"Hello World" not</code>
|
|
would just be <code>false</code>, for instance.</li>
|
|
<li><code>concat</code>: Stringifies the top two items on stack and concatenates them together in order.</li>
|
|
<li><code>strip_fname</code>: Cuts off the directories and the file extension of a file, going from "test/home/base.py.out" to "base.py", for instance.</li>
|
|
<li><code>copy</code>: Copy the top thing on stack.</li>
|
|
<li><code>count_back</code>: Pops the top two items off stack and searches for the first occurring index of the smaller string in the larger string. Don't get it? Read the code.</li>
|
|
<li><code>slice_left</code>: Pops the top two items off stack and, assuming one is a number, stringifies the other one and slices from the start of that to the index
|
|
represented by the number. This discards the character at the index, so <code>"hello,world" 5 slice_left</code> returns just "hello".</li>
|
|
<li><code>slice_right</code>: Same behavior as slice_left, except it slices the "right" side, so <code>"hello,world" 5 slice_left</code> would return "world".</li>
|
|
</ul>
|
|
Truthyness in Evals is not dissimilar to JavaScript. Empty strings are falsey, and all other strings are truthy; 0 is falsey and all other numbers are truthy, and booleans are truthy or falsey based on their value.
|
|
Sitix variables are considered truthy if the lookup is successful, and falsey otherwise; this allows for a replacement to the old <code>\[i exists]</code> and <code>\[i config]</code>,
|
|
like <code>\[i conf/prod]</code> would check if the <code>conf/prod</code> variable exists in scope (which could be set by <code>-c conf/prod</code>, for instance).
|
|
Evals will render Sitix variables as strings to run comparisons on them. This means you must be careful - if rendering that object would change a variable you don't want changed, for instance,
|
|
you'll end up with some very odd behavior. Rendering objects to strings is also dangerous because of the sheer size of some Sitix objects - you can store many gigabytes of data safely in
|
|
a PlainText object, which would be forced into main memory by an Evals comparison (Evals will not render Sitix objects unless they're used in a comparison with a string; comparing
|
|
two Sitix objects is safe). Be careful.
|
|
</div>
|
|
<div class="text">
|
|
And that's it! To see how these are used creatively in the wild, check out <a href="https://github.com/LinuxRocks2000/sitix-website">the source code for this website</a>.
|
|
</div>
|
|
<div class="text">
|
|
For a more thorough look at Sitix, check out <a href="https://github.com/LinuxRocks2000/sitix-rewrite">the source code</a>. There's a rather large comment at the start of
|
|
<code>main.cpp</code> that provides a deep look at Sitix syntax and usage.
|
|
</div>
|
|
[/]
|
|
[#templates/default.html] |