juji.func.system

System related built-in functions

-<-

(-<- rep sym value)

Assign value to a topic specific variable sym and return the value.

This is the same as -<-| except this variable only exists in the scope of the current topic and its followup-topics.

-<-|

(-<-| rep sym value)

Assign value to a global variable sym and return the value.

Example

;; The pattern below assigns value 5 to variable `?a`
;; If the pattern is used as trigger,
;; it will also trigger the corresponding action in the rule
[(-<-| ?a (+ 2 3))]

;; later, anywhere in the chat, the following pattern
;; is able to retrieve the value stored in `?a`
[(>- ?a)]

<-

(<- rep sym value)

Assign value to a topic specific variable sym and return nil.

This is the same as -<- except it returns nil.

<-|

(<-| rep sym value)

Assign value to a global variable sym and return nil.

This is the same as -<-| except it returns nil.

>-

(>- rep sym)

Return value assigned to variable sym.

add-background

(add-background rep topic-invocation)

Add a topic invocation to the background topics that runs periodically and does not remove itself after firing. Return nil.

add-background-once

(add-background-once rep topic-invocation)

Append a topic invocation to the background topics that runs periodically, but removes itself once fired. Return nil

add-input-translation

(add-input-translation rep translation)

Add the given text as the translation of the current user input. The added translations will be used in the subsequent matches in conjunction with the original user input. The translations have precedence over the original input during matching, and are tried in the order they are added. Once added, the translation has the same life cycle as the original user input.

answer-text

(answer-text rep qn)

Retrieve the answer text for question qn the last time it was asked.

For the current question in the conversation, its answer text may differ from the current user input because an answer text may be the concatenation of multiple rounds of user input.

answer-value

(answer-value rep qn)

Retrieve the answer value of question qn the last time it was asked. Answer value is specific to choice questions.

ask-for-more?

(ask-for-more? rep question)(ask-for-more? rep question threshold)

Return true if the input is short and the number of times the chatbot asked for more has not yet reach the threshold. threshold is 1 if not provided. Usually used together with update-ask-for-more-counter

ask-question

(ask-question rep qn)(ask-question rep qn wording)(ask-question rep qn wording mode)(ask-question rep qn wording mode question-tag)

Ask an open-ended question qn.

If wording (a string) is given, use it as the actual question wording; otherwise use the wording or heading from the defined question qn.

mode can be :first-time or :repeating. mode also affects question message when wording is nil:

  • if :first-time, wording of qn is used if available;
  • if :repeating, heading of of qn is used.

qn is one of the question variables defined in script. See https://juji.io/docs/reference/#question for detailed explaination on defining questions.

ask-question-gui

(ask-question-gui rep qn)(ask-question-gui rep qn {:keys [question-tag mode], :as option-map})

Ask question qn in GUI form. GUI form is usually used for asking single choice and multiple choice questions.

qn is one of the question variables defined in script. See https://juji.io/docs/reference/#question for detailed explaination on defining questions.

mode can be :first-time or :repeating.

capture-double

(capture-double _ i d f)

Convert the captured content to a double, the capture pattern is assumed to be [[:? #token/regex "\d+"] "." #token/regex "\d+"]

capture-identifier

(capture-identifier _ & ss)

Get the identifier from the captured content

capture-integer

(capture-integer _ & [i])

Convert the captured content to an integer, the capture pattern is assumed to be [#token/regex "\d+"]

capture-string

(capture-string _ & ss)

Get the string from the captured content, lower case them and interposing them with spaces

capture-string-lemmatized

(capture-string-lemmatized _ & ss)

Get the string from the captured content, lower case them and interposing them with spaces

capture-string-raw

(capture-string-raw _ & ss)

Get the string from the captured content, just concatenating the content without any changes

cleanup-chat

(cleanup-chat rep)

Clean up the server resource for this participation. This leaves the participation unfinished if (end-chat) has not been called. Refresh or reconnect leads to a new participation.

concat-tokens

(concat-tokens _ & tokens)

Concatenate the tokens into a single string. Often used as a normalization function for the captured content. Example Use

;; the following rule show the captured confirmation code
[my confirmation code is (?x [:s #token/regex "[a-z]+"
            #token/regex "[A-Z]+"
            #token/regex "[0-9]+"]
            concat-tokens)]
[?x]
;; input: my confirmation code is XYZ13NBC3
;; output: XYZ13NBC3

create-new-participation-question-map

(create-new-participation-question-map rep question)

current-chat-progress

(current-chat-progress rep)

Show a precentage of completed agenda topics. Return a float between 0 and 1.0.

current-topic-fired?

(current-topic-fired? rep)

Return true if the current topic generates a response.

day-of-week

(day-of-week _)

Present the day of the week of current UTC time.

end-chat

(end-chat rep)(end-chat rep redirect-url)

Finish the current participation and redirect to the specified page if redirect-url is provided. redirect-url is a string.

end-interview

deprecated

(end-interview rep)

End the current interview and redirect to the post-chat page after short delay.

This function is deprecated, please use end-chat instead.

exp

(exp exponent)

Natural exponential function.

first-agenda-topic

(first-agenda-topic rep)

Return the first agenda topic.

float-div

(float-div a b)

Return division results in decimal

force-chatbot-continue

(force-chatbot-continue rep)

Force the chatbot continue into the next topic without waiting for user input. This maybe useful to ask questions in a subtopic or making the background to terminate the current agenda topic.

get-ask-for-more-count

(get-ask-for-more-count rep question)

Count how many times the chatbot asked for more info regarding the given question.

get-current-question

(get-current-question rep)

Get the current question base on what on top of the stack. Assume the first question type argument is question.

get-date-by-offset

(get-date-by-offset _ offset)

Return a clojure instant in UTC after applying the offset.

get-fb-media-gui-titles

(get-fb-media-gui-titles _ gui-map)

Get the title of the given facebook media gui.

get-last-participation-question-map

(get-last-participation-question-map rep question)

Return the participation question map of the given question. For question related information intended to be persisted throughout the participation, participation question map is the right place to store. One can use update-last-participation-question-map to update.

get-next-question

(get-next-question rep)

Get the next question in agenda. Return nil if none exist. Ignore remarks.

get-nth-last-asked-agenda-question

(get-nth-last-asked-agenda-question rep n)

Return the REP’s nth last asked agenda question in the form of a map, return nil if it does not exist. when n is 0, the latest asked question is returned, 1 is the one before …

get-participation-question-attr

(get-participation-question-attr rep question attr)

Return the value of attr field in the given question’s participation question map.

get-question-heading

(get-question-heading _ question)

Question heading is used as unique identifier of a question,it should rarely be changed. This function should not be used for asking question, ask-question is the preferred function to do that.

get-task-completion-code

(get-task-completion-code rep)

Get the task completion code of the current participation. If the code does not exist, it will be generated and then returned.

get-web-media-gui-titles

(get-web-media-gui-titles _ gui-map)

Get the title of the given web media gui.

has-participation?

(has-participation? rep)

input-text-match-choice

(input-text-match-choice rep qn)

Check if the input text matches at least one of the choice in the question. Return a move message (a map) if it matches; return nil otherwise.

is-gui-question

(is-gui-question rep qn)

Check if qn is a GUI form friendly question (e.g., single choice, multiple choice question)

qn is one of the question variables defined in script. See https://juji.io/docs/reference/#question for detailed explaination on defining questions.

jump-to-topic

(jump-to-topic rep topic)

Return to the first appearance of the given topic in agenda. The function is called with topic-name. However, the topic-name will get resovled to topic-map by the REP engine.

make-choice-horizontal

(make-choice-horizontal _ q-map)

Make the choice question’s option horizontally displayed on web.

make-open-ended-question

(make-open-ended-question rep heading)(make-open-ended-question rep heading wording)(make-open-ended-question rep heading wording required?)(make-open-ended-question rep heading wording required? qid)

This is a wrapper to create an question map that can be passed into ask-question and record-answer function. heading, wording and qid are strings. required? is a boolean.

:required has default value true if not specified. wording has defualt value to be the same as heading, if wording is not specified or is nil. We recommend users not to specify qid, the system will generate a unique qid and it can be accessed in the returned question map. Please only specify it if you know what you are doing, and make sure the assigned qid is unique in the entire release.

make-request

(make-request rep base-url)(make-request rep base-url query-map)(make-request _ base-url query-map socket-timeout)

Make request to given url composed by base-url and querys in query-map. Return the body of the request results. Return nil if the request is not successful.

The keys of query-map (if exists and not nil) are argument names, values are the corresponding argument values. The keys and values will be url-encoded when forming the request url (e.g., “a b” becomes “a%20b”).

socket-timeout default to 10000, it is in milliseconds

[(make-request "http://sampleweb.com:1234/abc/def" {:k1 "10", :k2 "20"})]
;; the pattern above would make a request to "http://sampleweb.com:1234/abc/def?k1=10&k2=20" and return the request result

make-single-choice-question

(make-single-choice-question rep heading text-value-pairs)(make-single-choice-question rep heading text-value-pairs required?)(make-single-choice-question rep heading wording text-value-pairs required? qid)

Creates a single choice question. heading, wording and qid are strings. required? is a boolean. text-value-pairs is a 2d vectors with each row consists of its text and the corresponding value. The text is a string, whereas the value is a integer. e.g., [["text1" 0] ["text2" 1] ["text3" 2]] represents 3 choices.

:required has default value true if not specified. wording has defualt value to be the same as heading, if wording is not specified or is nil. We recommend users not to specify qid, the system will generate a unique qid and it can be accessed in the returned question map. Please only specify it if you know what you are doing, and make sure the assigned qid is unique in the entire release.

match

(match rep pattern)(match rep pattern input-text)

Test if the current user input matches the pattern, which is a quoted vector of match pattern. All namespaces in the given pattern need to be fully qualified unless the alias is defined in the same script. Example

(match '[hello])

match-stashed

(match-stashed rep pattern)

Test if the stashed user input matches the pattern, which is a quoted vector of match pattern. Example

(match-stashed '[hello])

multiple-choice-answer-values

(multiple-choice-answer-values rep qn)

Retrieve multiple choice answer values as a set.

outbound-redirect-url

(outbound-redirect-url rep target-url)(outbound-redirect-url rep target-url third-party-map)

Return a URL that will redirect to the target URL. An optional map can be used to add any third-party codes and values that will be stored in the participation results.

parse-number

(parse-number _ text)

Return nil if the text does not represent a number.

post-chat-url

(post-chat-url rep)

Return Juji’s post chat url.

pow

(pow base exponent)

Power function

question-answered?

(question-answered? rep qn)

Check if the question qn has any answer stored for the most recent time it was asked. Return the time of the answer if answered, otherwise, return nil.

question-asked?

(question-asked? rep question)

Check whether the question has been asked.

question-has-paraphrase?

(question-has-paraphrase? rep question)

Check whether question has any paraphrase.

question-response-failed?

(question-response-failed? rep question)

Return true if the question’s response is believed to be a failure. Usually used together with set-question-response-failed.

random-code

(random-code _ len)

Generate alphanumeric code of given length.

random-number-string

(random-number-string _ len)

Generate number string of given length

record-one-move-message

(record-one-move-message rep {:keys [value text question], :as move})

Record a single move message. A move message should include the following fields: :type, :gid, :question, :value, :text.

remaining-agenda-question-count

(remaining-agenda-question-count rep)

Check the number of questions remain in the agenda.

remaining-agenda-size

(remaining-agenda-size rep)

Check the remaining agenda size (i.e., how many topics left on the agenda)

required?

(required? rep question)

Check if the question is required. Return a boolean. If the :required field is not set, default to true.

reset-followup-conditions

(reset-followup-conditions rep)

Reset all followup and extended reply conditions. So previous chat does not trigger any followup and extended replies. Nevertheless, attributes remains.

return-to-question

(return-to-question rep question)

Return to the first appearance of the given question in agenda.

set-question-min-input-len

(set-question-min-input-len rep question threshold)

Set :min-input-len value in the given question map. The value need to be an integer.

set-question-response-failed

(set-question-response-failed rep question bool)

Set a boolean value to record whether the question response is considered a failure. Usually used together with question-response-failed?.

set-timer

(set-timer rep var-name t)

Set a timer at the var-name that expires t seconds from now, return nil.

This function is usually used with timer-expired?

skip-all-subtopics

(skip-all-subtopics rep)

Skip all sibling followup topics.

skip-next-subtopic

(skip-next-subtopic rep n)

Skip the next n sibling followup topics.

sleep-rep

(sleep-rep rep t)

Make the REP sleep for t milliseconds, return an empty string.

stash-input

(stash-input rep)

Save the current user input for later use, e.g. for match-stashed function

thin-text?

(thin-text? rep question)(thin-text? rep question input)

Checks if the user input is thin, i.e. not saying much. This is first check against :min-input-len in the question map, if that does not exsit, :thin-text-threshold in script is used instead. The input is considered thin if less than the threshold. When input is not given, length in calculated using input-length

timer-expired?

(timer-expired? rep var-name)

Check if the timer at the given var-name is expired.

This function is usually used with set-timer

update-ask-for-more-counter

(update-ask-for-more-counter rep question)

Update the ask-for-more counter. Increment the counter if it exists. Otherwise, set the counter to 1 if the question exists. Usually used together with ask-for-more?

update-last-participation-question-map

(update-last-participation-question-map rep question update-map)

Update participation question map, which is persisted throughout the participation, whereas the question argument in topic (e.g., ?q) only persists in the scope of the topic. get-last-participation-question-map function can be used to retrieve info from it.

wait-for-more-user-input

(wait-for-more-user-input rep)

REP will wait for more user input, return nil.