Formatting Rules (Unformat)
From AdamWiki
All versions of Unformat follow some basic rules. The newer versions of the program do some additional things.
The function of the program is to read one or more input files and remove the special formatting from the softcode in them so that the code can be entered into a TinyMUSH or other game server using the normal interactive player commands.
A coder might send a couple typical commands like these to the game:
Example 1:
&CMD-TEST me = $@test: @switch hasflag(%#, wizard) = 1, {@pemit %# = Test worked. You're a wizard.}, {@pemit %# = You ain't no wizard!}
&CMD-TEST-PLAYER me = $@test *: think setq(0, pmatch(%0)); @switch 0 = isdbref(%q0), {@pemit %# = I don't know who you mean ('%0').}, hasflag(%#, wizard), {@pemit %# = No, [name(%0)] is not a wizard.}, {@pemit %# = Yes, [name(%0)] is a wizard.}
Note that the command is all on one line, has no special formatting in it, and has no useful comments (real coders love comments, especially when the code is more complex than that). Coders also love to format their code with indentation that demonstrates the structure of their programs. Here's how a coder might want to write the same bit of softcode:
Example 2:
# Command: @TEST
#
# This command tells the user if they are a Wizard.
#
&CMD-TEST me = $@test:
@switch hasflag(%#, wizard) = 1, {
@pemit %# = Test worked. You're a wizard.
}, {
@pemit %# = You ain't no wizard!
}
-
# Command: @TEST player
#
# This command tells the user is another player is a Wizard.
#
&CMD-TEST-PLAYER me = $@test *:
think setq(0, pmatch(%0));
@switch/first 0 =
isdbref(%q0), {
@pemit %# = I don't know who you mean ('%0').
},
hasflag(%#, wizard), {
@pemit %# = No, [name(%0)] is not a wizard.
},
# else
{
@pemit %# = Yes, [name(%0)] is a wizard.
}
-
The formatted version has some comments at the top of the command (they're the lines that start with "#") and a "-" at the end to separate it from the next command. The code for the first command indents the two cases of the @switch so you can tell the "IF" part from the "THEN" part easily.
In the second command, the formatting is even more useful since this command is a little more complicated. The "@test *" command actually uses two commands (a "think" and a "@switch") and I've formatted these on separate lines. The @switch continues over 10-11 lines. Each of the three cases (isdbref? hasflag? else...) get their own little formatted section and each is indented the same amount. The }'s line up with the first character of the section for the {. The code that each case runs is indented further than the case itself.
When you run the code from Example 2 through Unformat, you'll get the compact version from Example 1, all one one line.
Once you get used to it, formatted code is much easier to work with than unformatted code. If you've been dealing with huge globs of unformatted code online, you might feel very comfortable with it, but everyone I've ever talked to who made the switch loves and prefers to write formatted code.
Contents |
Basic Formatting Rules
Here are the basic rules to Unformat.
Rule 1: Separate Commands with a Dash
Unformat can recognize that your file contains many different commands if you separate each command with a line containing only a dash (hyphen) as the first character. It has to be the first character, and some (buggy) versions of Unformat don't allow spaces after the dash.
Rule 2: Ignore Empty Lines
This is simple. If a line has nothing on it but spaces, Unformat will just skip it.
Rule 3: Ignore Comments
Any line that starts with a # is a comment and Unformat will just skip it. (The exception is in the case of special directives that start with #. See below.)
Rule 4: Commands Start on the First Column
At least in 1.1, Unformat requires you to start writing your command in column 1. That is, the first line of each command can't have spaces to the left of it.
Rule 5: Eat All Spaces to the Left of Text
Once it is "in" a command, Unformat throws away all spaces and tabs on the left side of any line. That is, you can indent stuff and Unformat will throw away the indentation.
Rule 6: Preserve All Spaces to the Right of Text
Any space on the end of a line is kept. If you need a space between words in a sentence that continues from one formatted line to another, put a space on the end of the first line.
That's it. The best way to figure out what it's doing is to look at some examples. Write some softcode in a file and run it through Unformat and see what happens to it.
Advanced Formatting Rules
Unformat has some special abilities, too. It can include one file inside another and newer versions can define and use variables and handle ASCII art text.
Rule 7: Add Inline Comments with /@@ @@/
Anything between /@@ and @@/ will be considered a comment and it will be tossed (including the /@@ and @@/). Note that just the comment code will be tossed, not the entire line (or lines), so you can drop comments into the middle of your code if you like.
Available: v2.0+
Rule 8: Include Files with #include
If you put #include on a line, followed by the name of another softcode file, Unformat will replace the #include line with the unformatted contents of the other file. This is useful if you have common code you want to share between codebases, or if you want to break up a large system into many different files, yet have a "master file" that can pull them all together.
Available: v1.1+
Rule 8: Define Variables with #define
If you have a constant you want to use throughout a softcoded system but you expect to change it often, use #define to create a variable or symbol and assign it a value. Then Unformat will replace every subsequent copy of that variable name with its value.
The syntax is #define symbol value. The symbol should not have spaces or tabs in it, but the value can.
Available: v2.0+
Rule 9: Handle ASCII Art with #ascii
Sometimes you want to create some nicely formatted ASCII-art menus or drawings for your programs, or you just need spaces not to get smooshed together by the MUSH parser. The #ascii directive will help you. Everything after an #ascii command (which should be on a line by itself) will be processed using some special rules, until Unformat reads another #ascii command.
When in ASCII-mode:
- A % character is changed to two % characters (% becomes %%) except when the % is followed by one of these: aclnopqsvACLNOPQSV0123456789#!].
- Two spaces in a row are converted to a space followed by a %b. For example, " " (7 spaces) is converted to " %b %b %b " before it is sent to the game.
- An actual TAB character is converted to %t.
- A \ character (backslash), { character (left curly brace), [ character (left square bracket), or ( character (left parenthesis) is escaped (prefixed) with a backslash. \ becomes \\. { becomes \{. [ becomes \[. ( becomes \(. This implies that you can't put [functions()] and stuff into #ascii blocks since Unformat will escape them and then the MUSH won't interpret them as code.
- Every newline character is replaced with a %r. That is, Unformat will take a bunch of lines in an #ascii block and make them all one line with %r's between them.
Consider the code in Example 3, below. Part of it is normal Unformat stuff, but it contains an #ascii block. (The stuff on a line after "#ascii" is ignored, so I write #ascii start" and "#ascii end" for clarity. The "start" and "end" don't actually mean anything special.) Within the #ascii block are three lines of code that I want to use for display. It contains some special characters — namely, the [ bracket and the %c_ ansi color escape sequences. The middle line also contains a lot of blank spaces that the parser would normally gobble up heartlessly.
Example 3:
&tr-header #1234 = @pemit %# = #ascii start %ch%cg==============================================================================%cn %ch%cy FiranMUX @Where [150 players connected]%cn %ch%cg==============================================================================%cn #ascii end -
Checking the #ascii rules, I see that Unformat should put a \ in front of the [ but leave the %c sequences alone. It will also replace the long block of spaces with alternating spaces and %b's. Last, it should make the three lines into one long line with %r's between them. Example 4 shows the result:
Example 4:
You'll have to scroll far to the right to see all of this code, since it's all on one long line.
&tr-header #1234 = @pemit %# = %ch%cg==============================================================================%cn%r%ch%cy FiranMUX @Where %b %b %b %b %b %b %b %b %b %b %b %b %b %b %b %b %b %b %b\[150 players connected]%cn%r%ch%cg==============================================================================%cn%r
Available: v2.0+
