Rit ver.1.3 Manual

2006/12/10
2006/08/24
Rit is a PHP like text processor that is designed for use in Plan 9. We can use full functionality of Rc. The name came from "rc in text".

General Rules

Dollar '$' is only one special symbol of Rit.
A dollar followed by:

variable: Variable is a sequence of alphas or numerics or '_', i.e., subset of environment variable.
'{': Rc script follows. The script continues up to '}'. Multi-line script is allowed. The terminator '}' must be out of rc string and out of { .. } nest.
'\n': NL (new line) escape

Usage

	rit [-Dbes] [file [arg ...]]

file and args

file is Rit text file. The file is one of script and args are passed to Rc scripts embedded in the file.
File name "." is special. That means stdin.

options

-D: Debug
-b: $0 in Rc is the file path without this option. If this option is given, $0 is base name of the file.
-e: Rit exits if error message is caught from Rc.
-s: Skip one line in the file.

Notations

Rit text: The text that is processed by Rit
Rc block: Block that is enclosed by "${" and "}" including "${" and "}".
Rc code area: Block that is enclosed by "${" and "}" excluding "${" and "}".
text area: Area that is extracted Rc block from Rit text.

Command execution

You can write rc script in Rc code area.
For example

Date: ${date}

will produce

Date: Thu Dec 23 10:17:10 JST 2004

Note that we have redundant empty line after this command; this comes from two subsequent '\n's: one from command and one from our text line. Avoiding this problem we have:

${date} continues nest line
${date}$ continues same line.

then the result will be:

Thu Dec 23 10:17:10 JST 2004
 continues nest line
Thu Dec 23 10:17:10 JST 2004 continues same line.

Variables

A dollar followed by alpha or numeric or '_'.

User: $user
This is equivalent to
User: ${echo -n $user}

The above three lines are converted to:

User: arisawa
This is equivalent to
User: arisawa

NL escape

A dollar at the end of line is NL escape. Example:

This line has NL escape. $
next line.

will be converted to:

This line has NL escape. next line.

Most rc commands produce NL at the end. We can avoid redundant NL by putting NL escape after } and/or before NL:

${pwd}$
this line will be next of pwd line.
${pwd}$$
this line will stays in the same pwd line.

the result:

/usr/arisawa/src/pegasus-2.1/rit
this line will be next of pwd line.
/usr/arisawa/src/pegasus-2.1/ritthis line will stays in the same pwd line.

Multi-Lines

Rit has full functionality with rc. For example Rit allows multi-line script:

${book='Alice in Wonder Land'}$
${echo -n 'echo test of multi-line:
line1: Carrol''s book:
line2: '$book'
line3: and we can use { and } in rc strings' }
Back slash new line escape in Rc command will work:
${echo -n one\
two }

These lines will be converted to:

echo test of multi-line:
line1: Carrol's book:
line2: Alice in Wonder Land
line3: and we can use { and } in rc strings
Back slash new line escape in Rc command will work:
one two

"if" and "switch" statement

We have 'if' statement:

${
	if(~ $user arisawa)
		echo ARISAWA
	if not
		echo NOT
}$

will produce:

ARISAWA

and

${switch($user){
	case arisawa
		echo ARISAWA
	case *
		echo NOT }}$

also produces:

ARISAWA

Note that { } nest is included in this example.

Comment in Rc command

Comment continues up to NL as Rc does.

${# This is a comment up to NL } this is also a part of comment
# this is also a comment
} # invisible
${# comment line1 terminated by Rc NL escape\
comment line2
} # invisible
$${# This isn't a comment but a part of text }

will produce:

 # invisible
 # invisible
${# This isn't a comment but a part of text }

Sequence of dollars

If a sequence of more than one dollars are appeared, then one dollar is simply discarded. Thus $$$$home is converted to '$$$home' and $$$${not a rc script} is converted to '$$${not a rc script}'. More than one sequence of dollars at the end of line $$$$ is not a NL escape. That is just converted to '$$$'.

$0, $1, $2, ...

$0 is special. This is a file name currently processed. $1, $2, .. are arguments. Dollar followed other characters is not a special. i.e.,

	$, $#

are shown as it is.

Reading Rit text from stdin and using Rc command such as "read" that read data from stdin can makes a problem. Never use stdin for Rit text in web applications.

Rit text from stdin

If Rit text is given from stdin, $0 is "#d/0",

term% rit . alice bob
$0
#d/0
$1
alice
$2
bob

where $0, $1, $2 are input and #d/0, alice, bob are output.

Rit text from a file

term% cat>foo
$0
$1
$2
term% rit foo alice bob
foo
alice
bob
term%

Rit executable

In most cases Rit will be used in executable file. Then the meaning $0, $1, ... are shown by the following example:

term% cat>bar
#!/bin/rit -s
$0
$1
$2
term% chmod 755 bar
term% bar alice bob
./bar
alice
bob
term%

If you want only base name of $0, you have -b option:

term% cat>bar
#!/bin/rit -bs
$0
$1
$2
term% chmod 755 bar
term% bar alice bob
bar
alice
bob
term%

Termination

${echo exit 'some message'>[1=2];exit} will terminate Rit.
Rc function "quit" is predefined in Rit:

	fn quit {echo exit $1 >[1=2];exit}

Simple Rc "exit" does not terminate Rit
but next ${ } block will terminate Rit because of error.
For example ${exit} ${} will terminate Rit.

Example 1

term% rit
${quit}
term% echo $status

term%

Example 2

term% rit
${quit abcd}
#<exit abc>
term% echo $status
rit 619: abcd
term%

Character code

Rit can handle UTF-8 character code.
Rit can also handle Japanese EUC code in text area but not in Rc code block.

Internals

Internally Rit makes a pipe to communicate rc. The pipe is in rc notation:

	bind -b '#|' /tmp

Rc codes in Rit text is sent to /tmp/data and Rc read /tmp/data1. You can see /tmp/data and /tmp/data1 by executing:

term% rit
${ls /tmp}

Stderr from Rc is used for synchronization.

Known Bugs

Use of "/bin/echo -n" can make a problem. The problem comes from "0 byte write problem to a pipe": letting foo be any executable, then it is not guaranteed that the following two commands

	foo > bar

and

	foo | cat > bar

produce same bar.

Avoiding this problem, rc function echo is predefined internally as

	fn echo {
		if(~ $1 '-n'){
			shift
			if(~ $"* ?*)/bin/echo -n $*
		}
		if not /bin/echo $*
	}