.. _plugin-factoids:

The Factoids plugin
===================

Reading factoids
----------------

.. _command-factoids-info:

factoids info [<channel>] <key>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gives information about the factoid(s) associated with *<key>*.
*<channel>* is only necessary if the message isn't sent in the channel
itself.

.. _command-factoids-random:

factoids random [<channel>]
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a random factoid from the database for *<channel>*. *<channel>*
is only necessary if the message isn't sent in the channel itself.

.. _command-factoids-search:

factoids search [<channel>] [--values] [--{regexp} <value>] [<glob> ...]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Searches the keyspace for keys matching *<glob>*. If *--regexp* is given,
it associated value is taken as a regexp and matched against the keys.
If *--values* is given, search the value space instead of the keyspace.

.. _command-factoids-whatis:

factoids whatis [<channel>] [--raw] <key> [<number>]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Looks up the value of *<key>* in the factoid database. If given a
number, will return only that exact factoid. If '*--raw'* option is
given, no variable substitution will take place on the factoid.
*<channel>* is only necessary if the message isn't sent in the channel
itself.

.. _command-factoids-rank:

factoids rank [<channel>] [--plain] [--alpha] [<number>]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a list of top-ranked factoid keys, sorted by usage count
(rank). If *<number>* is not provided, the default number of factoid keys
returned is set by the rankListLength registry value.

If *--plain* option is given, rank numbers and usage counts are not
included in output.

If *--alpha* option is given in addition to *--plain,* keys are sorted
alphabetically, instead of by rank.

*<channel>* is only necessary if the message isn't sent in the channel
itself.

Administration
--------------

.. _command-factoids-learn:

factoids learn [<channel>] <key> WORD <value>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Associates *<key>* with *<value>*.  *<channel>* is only
necessary if the message isn't sent on the channel
itself.  The WORD (defined in :ref:`supybot.plugins.Factoids.learnSeparator`)
is necessary to separate the
key from the value.  It can be changed to another word
via the :ref:`supybot.plugins.Factoids.learnSeparator` registry value.

.. _command-factoids-forget:

factoids forget [<channel>] <key> [<number>|*]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Removes a key-fact relationship for key *<key>* from the factoids
database. If there is more than one such relationship for this key,
a number is necessary to determine which one should be removed.
A * can be used to remove all relationships for *<key>*.

If as a result, the key (factoid) remains without any relationships to
a factoid (key), it shall be removed from the database.

*<channel>* is only necessary if
the message isn't sent in the channel itself.

.. _command-factoids-unlock:

factoids unlock [<channel>] <key>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Unlocks the factoid(s) associated with *<key>* so that they can be
removed or added to. *<channel>* is only necessary if the message isn't
sent in the channel itself.

.. _command-factoids-alias:

factoids alias [<channel>] <oldkey> <newkey> [<number>]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds a new key *<newkey>* for factoid associated with *<oldkey>*.
*<number>* is only necessary if there's more than one factoid associated
with *<oldkey>*.

The same action can be accomplished by using the 'learn' function with
a new key but an existing (verbatim) factoid content.

.. _command-factoids-change:

factoids change [<channel>] <key> <number> <regexp>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Changes the factoid #*<number>* associated with *<key>* according to
*<regexp>*.

.. _command-factoids-lock:

factoids lock [<channel>] <key>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Locks the factoid(s) associated with *<key>* so that they cannot be
removed or added to. *<channel>* is only necessary if the message isn't
sent in the channel itself.