====== Guru Customization (GURU.DAT) ======

The Synchronet //Guru// is an artificial conversational engine users can chat with for entertainment. Each [[config:chat_features#artificial_gurus|configured guru]] is backed by a small file in the [[dir:ctrl]] directory whose name matches the guru's [[config:chat_features#artificial_gurus|Internal Code]] (lowercased) with a ''.dat'' extension. The default guru's brain is ''[[dir:ctrl]]/guru.dat''.

A guru's "intelligence" is just a list of //expression / response// pairs evaluated top-down against the user's typed line. The first expression that evaluates true triggers a randomly-chosen response from its set. Sysops customize a guru by editing this file.

:!: The interpreter does not handle syntax errors gracefully. Make a backup before editing, and test changes against your own login.

===== File structure =====

<code>
(expression)
response
response
(expression)
response
response
()
response
response
response
</code>

  * Expressions are enclosed in parentheses ''(...)''.
  * Each expression is followed by one or more response lines.
  * The final expression must be the empty //fall-through// expression ''()''. Omitting it is a syntax error.
  * Total file size is limited to 64 KB (or available memory).

Evaluation is **top-down**. As soon as one expression matches, its response set is used and remaining expressions are ignored for that input line. Only one response per input line is selected.

===== Expressions =====

The simplest expression is a literal uppercase string (with or without spaces). The user's input is uppercased before comparison.

  * Strings cannot contain ''~'', ''^'', ''|'', ''&'', ''('', or '')''.

==== Match modifiers ====

^ Modifier ^ Position ^ Meaning ^
| ''~''    | suffix   | Match even when the string is **embedded** in a larger word. ''(HELLO~)'' matches the user typing ''XhelloX''. |
| ''^''    | suffix   | Match only when the string is at the **start** of the input line. ''(HELLO^)'' matches ''Hello there'' but not ''I said, Hello!''. |

==== Logic operators ====

^ Operator ^ Meaning ^ Example ^
| ''&''    | AND     | ''(HELLO&GURU)'' — both strings must appear in the input |
| ''%%|%%''| OR      | ''(HELLO%%|%%HI)'' — either string |
| ''( )''  | Group   | ''(GURU&(HELLO%%|%%HI))'' — nested logic |

==== ARS expressions ====

An expression may include an [[access:requirements|ARS]] in square brackets ''[ ]'' for user-attribute matching. Example:

<code>
(HELLO&GURU&[LEVEL 20])
</code>

Evaluates true only if the user typed both ''HELLO'' and ''GURU'' **and** their security level is 20 or higher. See [[access:requirements|Access Requirements]] for the full ARS syntax.

===== Responses =====

Each expression can be followed by up to **100 responses**, each up to **512 bytes**. The Guru picks one at random from the matching expression's response set.

  * Responses cannot contain ''('' or '')''.
  * A response may span multiple lines if each continued line ends with a back-slash ''\''.
  * The more responses an expression has, the less the Guru repeats himself.

==== Response variables ====

A back-quote (''`'') character followed by one of the variables below substitutes a dynamic value (or performs an action) inline:

^ Variable ^ Meaning ^
| ''`A''   | User's alias (or name, if aliases are not allowed) |
| ''`B''   | User's birth date |
| ''`C''   | User's computer / host description |
| ''`D''   | User's download bytes |
| ''`G''   | Guru's name |
| ''`I''   | System's QWK ID |
| ''`J''   | Current day of month |
| ''`L''   | User's [[access:level|security level]] |
| ''`M''   | Current month |
| ''`N''   | User's note (location, if aliases not allowed) |
| ''`O''   | Sysop's name |
| ''`P''   | User's phone number |
| ''`R''   | User's real name (address, if aliases not allowed) |
| ''`S''   | System name |
| ''`T''   | Current time |
| ''`U''   | User's upload bytes |
| ''`W''   | Current day of week |
| ''`Y''   | Current year |
| ''`Z''   | User's ZIP/postal code |
| ''`$''   | User's [[access:credits|credits]] |
| ''`#''   | User's age |

==== Action variables (local-only) ====

These have effect only when the user is in **local** chat with the Guru (not in [[config:chat_features#multinode_chat_channels|multinode chat]]):

^ Variable ^ Effect ^
| ''`H''   | Hang up on the user immediately |
| ''`Q''   | Quit chat (the only way to exit Guru chat without ''Alt-G'' locally) |
| ''`!''   | Toggle the Guru's typing-mistake mode on/off |
| ''`_''   | Pause briefly mid-response |

===== Example =====

<code>
(HELLO)
Hello there, `a...
Hi `a, what's new?
Hey `a — how's the weather in `n?
</code>

If a user named //Joey// from //Bigfork, MT// types ''hello'', the Guru randomly picks one of the three responses. ''`a'' is replaced with ''Joey'' and ''`n'' with ''Bigfork, MT''.

For more elaborate examples, see the default ''[[dir:ctrl]]/guru.dat'' that ships with Synchronet.

===== See Also =====
  * [[:custom:|Customization index]]
  * [[config:chat_features#artificial_gurus|Configuring Artificial Gurus in SCFG]]
  * [[access:requirements|Access Requirements (ARS)]]
  * [[dir:ctrl]] — location of ''guru.dat''

{{tag>guru chat customization}}
