Kawari - KIS Reference Manual

Kawari Inline Script (KIS) is a simple language that can be used in the dictionary files of Kawari. By using inline scripts, you can add words to the dictionary while running Kawari, and perform processing according to events notified from the body.

2. Format

Inline script is described by enclosing it with "$(~)" in an entry definition. A block surrounded by one "$(~)" is called an "inline script block". Multiple statements can be written in one block. Separate statements with a semicolon (";"). A statement consists of a command and zero or more arguments. Separate commands, semicolons, and arguments with one or more spaces.

3. Evaluation, Return Value, Truth Judgment

When a block is interpreted by Kawari through an event call, an utterance request, etc., it is called "evaluation". When a block is evaluated, it returns a "return value". The return value is a single character string, and what kind of return value is returned depends on the command. Some commands always return """"(an empty string).

If a block consists of multiple statements, the return value of the block is the return value of all statements in the block in sequence. Note that if you don't want the block to return a return value, you can suppress it using the silent command.

When Kawari evaluates a return value and determines whether it is "true" or "false" in Boolean algebra, it uses the following criteria:

This truth/false judgment is common to both syntax commands and function commands, which will be described later. If you add your own commands, please use this standard for authenticity judgment.

4. Commands

Commands can be broadly classified into two categories: syntax commands, such as the if and while commands, and function commands, such as the adddict and date commands. Syntax commands control the flow of processing according to the truth or falsehood of given conditions. Function commands, on the other hand, perform the actual processing according to the given arguments. ^*1 ^*2

Where there is no danger of confusion, syntax commands are sometimes referred to as "syntax" and function commands as simply "commands".

4.1. Command List

Syntax Commands
if	Evaluates a statement and executes commands accordingly
foreach	Executes commands for all words in a specified entry
loop	Executes commands for a specified number of loops
silent	Suppresses block outpu
until	Loops until a condition is met
while	Loops while a condition is true
break	Breaks out of a loop
continue	Returns to the top of a loop
NULL	Returns an empty string
?	Randomly selects and evaluates
function	Defines a function
rmfunc	Deletes a user created function
return	Escapes from a function

Function Commands
Dictionary Manipulation
Common Dictionary Operations	Operations Common to Dictionary Manipulation Commands
set	Sets a definition for an entry
setstr	Sets an entry to a string
adddict	Adds a definiton to an entry
adddictstr	Adds a string to an entry
push	Adds a definition to an entry
pushstr	Adds a string to an entry
unshift	Inserts a definition at the beginning of an entry
unshiftstr	Inserts a string at the beginning of an entry
insert	Inserts a definition at a specific position in an entry
insertstr	Inserts a string at a specific position in an entry
get	Gets all definitions in a dictionary
getcode	Gets all definitions in an entry without evaluating them
getrandom	Gets a random definition from an entry
pop	Removes the last word of an entry and returns it
popcode	Removes the last word of an entry and returns it without evaluating it
shift	Removes the first word of an entry and returns it
shiftcode	Removes the first word of an entry and returns it without evaluting it
clear	Removes a string from an entry
cleartree	Removes a string from an entry tree
size	Counts the number of definitions in an entry
find	Returns the first position of a string in an entry
rfind	Returns the last position of a string in an entry
copy	Copies an entry's content to another entry
copytree	Copies an entry tree's content while maintaining entry structure
move	Moves an entry's content to another entry
movetree	Moves an entry tree while maintaining entry structure
listsub	Gets a list of subentries
listtree	Get a list of entire entry tree
writeprotect	Makes an entry unwritable
File Manipulation
save	Saves an entry to a file
savecrypt	Encrypts and saves an entry to a file
load	Loads a Kawari formatted dictionary file
textload	Reads a text file
textappend	Appends to a text file
textsave	Saves a text file
readdir	Loads a directory
cncpath	Makes the pathname available to the system
dirname	Extracts the directory name from a path name
filename	Extracts a file name from a path name
isexist	Determines if a file exists
isdir	Determines if a file is a directory
isfile	Determines if a file is a regular file
Counters
dec	Considers the given entry definition as a number and subtracts from it
inc	Considers the given entry definition as a number and adds to it
String Manipulation
length	Gets the length of a string
match	Gets the first position of a substring
rmatch	Gets the last position of a substring
match_at	Determine if a substring exists at a specified position
substr	Gets substring
char_at	Gets the character at a specified position
sub	Replaces the first string that matches
gsub	Replaces all matching strings
rsub	Replaces the last matching string
tr	Replaces characters
reverse	Reverses a string
tolower	Turns all characters lowercase
toupper	Turns all characters uppercase
chr	Returns one character of a specified character code
split	Splits a string by a delimiter
join	Joins strings by a delimiter
compare	Compares strings
SAORI
saoriregist	Registers a SAORI
saorierase	Unregisters a SAORI
saorilist	Returns a list of register SAORIs
callsaori	Calls a registered SAORI
callsaorix	Calls a registered SAORI (High functionality version)
Communicate Commands
communicate	Evaluate all words in an entry and randomly select one from the values
matchall	Returns true if all keywords are in a string
Output Commands
echo	Connects arguments with whitespace characters and returns
encode_entryname	Converts to a valid entry name
escape	Escapes from SakuraScript in an argument
Auxiliary Commands
entry	Calls an entry
entrycount	Return the total number of entries
eval	Re-evaluates word
urllist	Outputs recommendation list in SHIORI/2.5 format
wordcount	Returns the total number of words
xargs	Expands arguments and then executes them
Miscellaneous Commands
rccharset	Specifies Character set setting of error messages
date	Returns the date and time in a specified format
mktime	Converts the date and time to elapsed in seconds
getenv	Returns the contents of an environment variable
help	KIS Commandline help command
logfile	Specifies a logfile
loglevel	Specifies what to log
logprint	Outputs to log
debugger	Turns Kosui ON or OFF
rand	Returns a random integer
srand	Set the random number seed
Specifies security level	セキュリティレベルの指定
ver	Gets Kawari version number

4.2. Command Reference

4.2.1. Syntax

4.2.2. Dictionary Manipulation

4.2.3. コマンド-ファイル操作

4.2.4. コマンド-カウンタ

4.2.5. 文字列操作

4.2.6. コマンド-SAORI

4.2.7. コマンド-コミュニケート機能

4.2.8. コマンド-出力

4.2.9. コマンド-補助機能

4.2.10. コマンド-その他

Appendix

I. インラインスクリプトの追加方法

インラインスクリプトの関数コマンドは、簡単に追加できるよう、華和梨の他の部分と別のフォルダにソースが収めてあります。srcフォルダ中のkisフォルダがそれです。自分で"華和梨"を拡張する際、KISの追加だけで望む機能が得られるか、まず検討して下さい。この場合、華和梨のほかの機能へ与える影響が少なく、無用のエンバグを避けられます。また、他の人がソースコードを再利用しやすくなるはずです。

良いKISができたら、ぜひ教えてください。オリジナルの"華和梨"にも採用したいと思います。

II. 注釈

*1 構文コマンドと関数コマンド

*2 インラインスクリプトに渡される引数の数

コマンドに引数を与える時、エントリ呼び出しで与える場合を考えます。

このケースで、EntryNameエントリに何もセットされていない場合を考えます。この場合、echoコマンドの第1引数は""で、第2引数が「Hello」になります。第1引数が「Hello」ということはありません。インラインスクリプトに渡される引数の数と位置は、エントリ解釈の前に確定します。

Format	$(break)
Return Value	None
Function	Exit loop syntax such as loop, until, while, foreach, etc.
Example # Check the word in the data entry and exit the loop if it is "END". $( setstr @count 0; loop $(size data) $( if $[ $data[${@count}] == "END" ] $( break; ) else $( inc @count; ); ); get data[${@count}]; )

Format	$(continue)
Return Value	None
Function	In a loop syntax such as loop, until, while, foreach, etc., terminate the current loop process and enter the next loop process.
Example # Only words in the data entry that contain "ghost" are copied to the data2 entry. $( loop $(size data) $( setstr @count ${-1}; echo $data[${@count}]; if $[ $data[${@count} !~ "ghost" ] $( continue; ); pushstr data2 $data[${@count}]; ); )

Format	$(function FunctionName functionDefinition) $(function Functionname)
Return Value	If provided two arguments, none. If provided one argument, return a string representation of the function definition.
Function	Define a function command. During the function definition, the "@arg" entry can be used as an argument. $@arg[0] is the function name, and the arguments start at $@arg[1]. The return value of the entire function definition is the return value of the function. A command with the same name as a built-in function (but not a syntax command) can be defined. If a built-in command and a user-defined command with the same name exist, the user-defined command is invoked first. In this case, the original command can be called by prefixing it with ".". at the beginning of the command, the original built-in command can be forced to be called. If the argument is only a function name, a string representation of the content of the function definition is returned. This return value is equivalent to writing the content of the function definition in an entry and calling the entry with the getcode command.
Example =kis # Define a function that returns the value set in the entry function tset $( # do nothing unless 2 arguments if $[ $(size @arg) != 3 ] $(return ""); set $@arg[1] $(getcode @arg[2]); get @arg[2]; ); # Store the definition of user-defined function tset in funcdef entry set funcdef $(function tset); =end

Format	$(if conditional statement true else false) $(if conditional statement true else false) $(if conditional statement true else if conditional statement 2 ...)
Return Value	Returns the statement if true or false.
Function	Executes a true-case statement or a false-case statement depending on the truth of the conditional statement. The else if clause can be connected to any number of clauses. A space character or a newline character is always required before and after a command such as else.
Example 1 $(if $[ ${mode} == "Y" ] "\0Yes\e" else "\0No\e") # Display "Yes" if the search is for "Y" in the content of the mode entry. # Otherwise, "No" is displayed Example 2 $(if "true" $(set a "1" ; set b "2") ) # Sets entry a to 1, and entry b to 2 using a compound statement. Example 3 =dict a : 1 b : 2 =end =kis if $[ ${a} == "1" ] $( if $[ ${b} == "2"] $( echo "Overlapping"; ) else $( echo "Not Overlapping"; ); ) else $( echo "Not Overlapping"; ); =end # Example of nesting if statements. # "Overlapping" is echoed.

Format	$(foreach entry1 entry2 statement)
Return Value	Result of evaluating statement for all words in entry 2
Function	Set all of the definitions in entry2 to entry1 and evaluate the statement for each definition. If a substitution blcok is used for the string, enclose it with $(), etc.
Example $(set N 0 ; foreach i npw $(echo "Sir "${i}", "; inc N); echo ${N}" people") # Call "Sir "${i}", " for every person name in the npw entry as i, # and display the number of people at the end with ${N}" people".

Kawari Inline Script Reference Manual

Index

1. Overview