CX Setup Official Documentation (v2.0.N)

This documentation is licensed under the GNU Free Documentation License (GFDL). Therefore, all edits, reuses and whatnot of this documentation (valid for both Org and HTML versions of the docs) must comply with GFDL’s terms and conditions.

If you wish to contribute to the documentation, I’d really appreciate it. However, there are some rules and guidelines you must follow:

• KISS: Keep It Simple, Stupid. Make sure your changes do not affect the simplicity and readability of the documentation in a negative way.
• If it ain’t broken, don’t redesign it. Do not propose changes to how the UI should look, as the current combination of HTML and CSS aims for simplicity, due to the fact it’s very objective.
• Editing the HTML export is like painting a screenshot — impressive, but pointless. Make Pull Requests for the Org files, not the HTML ones.
• Fixing typos is noble; flooding PRs with them is chaos. Typo squatting is perfectly fine and helpful, but don’t make too many Pull Requests to fix typos in a row, as it causes unnecessary spam. The best alternative is to “bundle” several typo fixes in one PR.
• There are no stupid questions — only unanswered ones (and I try to avoid those). If you have any questions, don’t hesitate to ask, as I try to reply to all. You can use the following e-mail: real_mf366@yahoo.com.

If those rules did not scare you away, the GitHub repository is right here. Thanks ahead for your contributions.

Quite possibly, one of the simplest keywords. Outputs something to the screen without a newline.

These ones are also extremely simple: all they do is output new lines to the screen. ENDL outputs 1 newline, while ENDL2 outputs 2.

These 3 keywords all serve the same general purpose: styling text. To better understand them, they’ve been split into 3 tables, one for each.

This is the keyword responsible for terminating the script safely instead of waiting for the end of the file.

New in v2.0.0, this overload of TERMINATE allows for more verbosity.

It can be given a custom exit message that will be shown if the ExitCode is not 0.

This is the overload of CIN that requires no arguments.

CIN is the most basic tool for getting input from the user (more specifically, stdin).

This is the overload of CIN that requires 1 argument.

Sometimes, you might need to set a character limit on a user’s input. That way, even if they type more than that, only the first x characters actually get cached.

Given CXSetup is used in ContenterX’s setup scripts, it’s kind of an obligation for it to allow the creator of the script to run sub-processes programatically.

This is the overload of CIN that requires 2 arguments.

Other than setting a character limit, this overload also allows you to set a custom prompt message for the input.

The only disadvantage is that applying a character limit becomes mandatory. However, you can get past that due to how the character limit works.

Sometimes, you may need to be more discreet with your inputs. For example, it’s not really a great idea to get passwords with CIN, since it shows what is being typed.

GETPASS solves such issue. With this keyword, you can safely get passwords without showing them on screen. This keyword’s only limitation is, unironically, the fact it cannot be limited to a certain number of characters (any amount is accepted).

CIN has yet another big issue: when it is given a character limit, it makes sure the input doesn’t go beyond the limit. However, it does not make sure the input has the specified length.

This might not seem problematic, but it becomes when cache grabs are involved. Cache grabs will be a matter of discussing later, due to their complexity. However, here is a small representation of the issue.

>>> CIN ?? 4 ?? "Your input please: ";
Your input please: Good
>>> COUT ?? c0:4l:1:3:n;
Good

No issue at first. Well let’s move on to the second example.

>>> CIN ?? 4 ?? "Input: ";
Input: Ok
>>> COUT ?? c0:4l:1:3:n;
Ok
>>> CIN ?? 1 ?? "Input: ";
Input: A
>>> COUT ?? c0:4l:1:3:n;
OkA

Now, imagine the first input was done to ask for the path of a very important file. But, before the file is used, another input is done.

Now, CXSetup would think the file is named OkA, when it is actually named Ok.

To avoid this issue, we can safely use SAFECIN. To make sure the input is as long as we want it to be, SAFECIN pads the right of the input with spaces (if necessary) until the length of the input matches.

Then, when doing the cache grab, we can trim the spaces if necessary.

Here’s our example, but refined. To better illustrate it, the meaningful whitespace characters have been represented as [SPACE].

>>> SAFECIN ?? 4;
An input is required (press Enter to ignore it): Ok
>>> CIN;
An input is required (press Enter to ignore it): A
>>> COUT ?? c0:4l:1:3:n;
Ok[SPACE][SPACE]
>> COUT ?? c0:4l:1:3:b; // the little b means trim both sides - we'll talk about it soon
Ok

Sometimes, it might also be useful to specify exactly what input must be given.

For example, which of these scenarios is clearer from the user side (a.k.a. by someone who doesn’t see the underlying script), A or B?

Scenario A:

Your input, please:

Scenario B:

Please insert a valid path to the configuration file:

ECHO does not write to the screen by default. It is used to write to a file instead. If you wish to output to stdout, please use the COUT keyword.

Another useful feature in a scripting language is the ability to write to a file. Even though ECHO is limited, it is still a very good option when it comes to writing to files.

Note that ECHO does not overwrite files. In fact, there are 2 special cases and a more generic one:

1. Generic Case: ECHO successfully writes to a file.
2. FileExistsError: ECHO fails and throws an Exception. This happens if the file already exists.
3. Reverts to COUT: Yes, in theory, you can use ECHO instead of COUT, if you give ECHO an empty string instead of an actual file path. However, it’s not really that good of an idea.

A more extreme version of ECHO, this one is fine with the possibility of overwriting files. Due to this fact, it ought to be used carefully.

The main issue with RUN is the fact it ends up hardcoding values.

For example:

RUN ?? "pip" ?? "install" ?? "simple_webbrowser";

What if we want the system to tells us exactly what version of pip, npm or the package manager to use? The solution is extremely easy.

PIPRUN ?? "install" ?? "simple_webbrowser";

All of these work essentially the same way as RUN (they’re wrappers), so their tables have been omitted (see the RUN command for more information).

Another important thing when it comes to installing software are requirements!

Note that REQUIRES merely defines requirements, it does not install them.

Due to the slight complexity of one of its arguments, instead of just showing the table we’ll also show a demonstration with comments.

>>> REQUIRES ?? 0 ?? "neofetch"; // the 0 stands for "Install using system package manager"
>>> REQUIRES ?? 0 ?? "cowsay"; // worth mentioning the command does not output anything or install anything
>>> REQUIRES ?? 1 ?? "MF366-Coding/WPlugZ-CLI"; // the 1 uses ContenterX itself to install ("Install using ContenterX")
>>> REQUIRES ?? 2 ?? "NCapybaraLib"; // the 2 stands for "Install using pip"
>>> REQUIRES ?? 3 ?? "express"; // source number 3 stands for "Install using npm"
>>> REQUIRES ?? 4 ?? "https://github.com/MF366-Coding/WriterClassic/releases/download/v11.0.0/WriterClassic_v11.0.0_SetupWizard_x64.exe"; // source number 4 stands for "Get binary from a direct link" - you'll be using this a lot in Windows
>>> REQUIRES ?? 5 ?? "sl"; // this is a ValueError - only sources [0,4] are available

So, in summary:

After marking all the dependencies you need, it’s time to install them. And that’s exactly what this command does. Now, you can call REQINSTALL more than once in the same script, but keep in mind that after each call, the list of dependencies is wiped clean.

There’s a whole new syntax when it comes to accessing caches. Its official name is cache grabbing.

A cache grab can have any data type, since it does not matter which command saved the cache.

For example, you can do a CIN operation, which saves a string. But that hardly matters, because you can access that same cache as if it were an integer.

The syntax for cache grabs is the following and can be used as arguments for keywords:

AB:CD:E:F:G

So what does each letter stand for? Let’s see:

• A: this must always be set to a lowercase C (c).
• B: an integer. This is used as the start index for the cache grab. For example, 0 in this case means start from the beginning.
• C: an integer. Can be an end index or the length of the cache grab. For example, 5 can either mean end at the index before 5 (4) or end 5 bytes after the starting index (with 0 as the starting index, it would be 5).
• D: a single character, must be one of l or e. This is the value that decides whether value C is interpreted as the end index (e) or the length of the cache grab (l).
• E: an integer. Represents the step value. This represents the pattern to perform. Let’s say we’re cache grabbing Hello, World!. Using a step value of 1 (default), we’d get Hello, World! but a step value of 2 would give us the same string, but skipping each odd-indexed character (indexing starts at 0). So, Hlo ol!.
• F: an integer. Represents the data type the cache grab must be casted as. (See table below.)
• G: a single character, must be one of b, r, l, n, B, R, L, N, v, e, k, m. This value must always be set to n if we’re not dealing with cache grabbed strings. If it’s strings we’re dealing with, however, we can use this value to decide whether spaces should be trimmed or not (n is trim none), and from what direction (r is trim right, l is trim left and b is trim both sides). This is useful when used alongside SAFECIN, for example (since it pads the input with spaces).

Here’s an example:

>>> SAFECIN ?? 6 ?? "6 characters only please: ";
6 characters only please: Hello!
>>> COUT ?? c0:6l:1:3:b; // the first 6 characters, no pattern, output as string, trim both sides
Hello!

Writing can only be done through keywords, albeit in 2 different ways:

• Directly: A direct modification involves the script creator themselves using a method that does not require any sort of confirmation from the user when it comes to modifying the cache.
• Indirectly: An indirect modification involves obtaining input from the user or the environment.

Cache is an extremely powerful tool, as it allows for many things. 2 examples are shown below:

• Constants. The equivalent to constants would be this (at the start of the script): SET ?? 7; and accessing it like this: c0:1l:1:1:n.
• User Feedback. Hey, the user knows best, right? You can obtain file paths, make decisions and much more, based on the user input.

Let’s say, for example, there’s a dependency our setup script needs, but in a version of the OS, it’s named x-dev and in another version of the very same OS, it’s named x-pkg. Clearly, this is going to raise issues. Thankfully, we can instruct the user on how to check what the name is and then ask them if it’s one or the other. The only problem is that we cannot achieve comparisons.

Sure, we could do something like this, since both package names have exactly 5 characters:

COUT ?? "Here's how to check whether the name is x-dev or x-pkg: etc etc etc...";
ENDL;
SAFECIN ?? 5 ?? "The name: ";
PKGRUN ?? "install" ?? c0:5l:1:3:b;
TERMINATE;

However, there are several issues with this script.

1. The user can input ANY name, which is problematic: they could be installing something they don’t know is safe.
2. The user isn’t restricted to 5 characters, they can insert a string with 1, 2, 3, etc.

So, how can we fix this code? Using polarity. Polarity has quite an unusual syntax.

In a script, polarity always starts off positive. Here’s an example of a positive keyword:

+ENDL; // positive keyword - can only be done like this in v2.0.0 and above

You can, however, omit the + sign and it will still be interpreted as a positive keyword:

ENDL; // still a positive keyword - the only correct way to use one in v1.0.0

A negative keyword would look like this:

!ENDL; // negative keyword

There is also another behavior declaration available - the indifferent declaration, introduced in v2.0.0:

&ENDL; // indifferent keyword - new in v2.0.0

Indifferent keywords will run no matter what: they’re indifferent to the polarity.

Getting back to our script, here’s a refined version:

// the polarity starts off positive so we don't have to worry about COUT not running
COUT ?? "Here's how to check whether the name is x-dev or x-pkg: etc etc etc...";
ENDL; // command is positive so it runs, because the polarity is also positive
COUT ?? "Is the correct name 'x-dev'?"; ENDL;
YAYORNAY;
// polarity has now changed: YAYORNAY modified it
PKGRUN ?? "install" ?? "x-dev";
// the command above is positive so it will only run if the polairty is positive (if the user pressed 'y')
!PKGRUN ?? "install" ?? "x-pkg";
// the command above is negative so it will only run if the polarity is negative (if the user pressed 'n')

// we can clear the polarity by doing an indifferent reset
&RESET;

// That way, we don't have to do TERMINATE; !TERMINATE;, because we already know the polarity is going to be positive
TERMINATE;

// or, better: we could have just done &TERMINATE;
// Done!

Quite a complex example, I admit. Any command can be negated.

This keyword simply resets the cache back to positive.

That is why it should only be used with a ! or a & declarations, as it does not make sense to RESET an already positive polarity.

This keyword inverts the polarity.

Gets input from the user and adjusts the polarity accordingly (y = POSITIVE, n = NEGATIVE)

There are other keywords that can affect the polarity of the script, however. They are:

• PATH.EXISTS - Verifies if a given path exists
• DIR.EXISTS - Verifies if a given directory exists
• FILE.EXISTS - Verifies if a given file exists