1. Overview

Freetalk is a freely available console based Jabber client-cum-bot. It has many features, but to highlight,

• Highly extensible through ‘Scheme’ language. (see section Customizing freetalk) (see section Extension language)
• Console based client with Readline interface featuring command line editing, history, context sensitive autocompletion etc … (see section Tips and Tricks).
• Most of the features in Freetalk are fully customizable, either through command line arguments (see section Invoking), or startup file (see section freetalk.scm)
• With a new concept called ‘dynamic-commands’, a command can appear and disappear dynamically, based on the context.
• history feature records all your conversions in ‘~/.freetalk/history/login-id/buddy-name’.
• Finally, Freetalk is free software. This means that everyone may use it, redistribute it and/or modify it under the terms of the GNU General Public License, as published by the Free Software Foundation (see section Freetalk License)

2. Invoking

Invoking Freetalk at command prompt is very simple. The following are the possible command-line arguments supported,

• freetalk [options]
  where options are,
• -j=Jabber-id | –jid=Jabber-id
  Jabber-id is your Jabber ID.
• -s=SCRIPT-FILE | –script=SCRIPT-FILE
  Invoke script/bot mode with SCRIPT-FILE as the source.
• -V | –version
  Gives the current version of Freetalk. This option does not accept any argument.
• -? | –help | –usage
  Gives a brief help on the above options. This option does not accept any argument.

3. Freetalk commands

3.1 Freetalk command - connect

command: /connect

Connect to the configured jabber server (see /server).

~\/~ /connect Connecting... ~\/~

If server is not configured, it displays an error message and stops

~\/~ /connect Server not set ~\/~

3.2 Freetalk command - disconnect

command: /disconnect

Disconnect from the currently connected server.

~\/~ /disconnect Disconnected from server. Reason (0): User request ~\/~

3.3 Freetalk command - server

command: /server [servername]

Specify the servername which you want to connect, or display the currently set server.

~\/~ /server Current server: ~\/~ /server jabber.org ~\/~ /server Current server: jabber.org ~\/~

3.4 Freetalk command - jid

command: /jid [user@domain[/resource]]

Specify the Jabber ID which you want to use, or display the currently set Jabber ID.

~\/~ /jid Current JID: ~\/~ /jid avati@jabber.org ~\/~ /jid Current JID: avati@jabber.org

This command is meant to be used when changing accounts and quick logins.

3.5 Freetalk command - add

command: /add user@domain

This command sends a buddy add request to user@domain into your buddy list.

~\/~ /add harshavardhanacool@gmail.com ~\/~

3.6 Freetalk command - allow

command: /allow user@domain

Allow the user to see (“subscribe to”) your status. Note that this command does not add the user to your buddy list; if you must do that, use /add.

~\/~ /allow haddock@marlinspike.org

3.7 Freetalk command - deny

command: /deny user@domain

Deny the user permission to see (“subscribe to”) your status.

~\/~ /deny cacafonix@village.gl

3.8 Freetalk command - quit

command: /quit message

Quits Freetalk with a banner.

~\/~ /quit shell$

3.9 Freetalk command - restart

command: /restart

This command restarts Freetalk.

~\/~ /restart Loading dictionary [/usr/share/dict/words]... [38619] words Jabber ID:

3.10 Freetalk command - prompt

command: /prompt [type]

This command sets the prompt with specified type

~\/~ /prompt ~qp~ ~qp~

3.11 Freetalk command - pipe

command: /pipe buddy command [options]

Pipe the output of command to buddy. options are passed to command.

~\/~> /pipe harsha@gmail.com ls -alh ~\/~>

3.12 Freetalk command - port

command: /port [port]

/port command sets the specified TCP port to be used for the next /connect.

Example:

~\/~> /port 995 ~\/~>

3.13 Freetalk command - shell

command: /shell [command] [args …]

/shell command executes the specified command with its args. With no arguments, /shell escapes to shell. You can also chat with shell as if shell is your buddy. Just type shell without / prefix.

Example:

~\/~> /shell ls -lh /tmp total 12k drwxr-xr-x 3 root root 4.0k Jan 1 00:53 emacs-terminfo -rw-r--r-- 1 root root 1 Jan 1 05:04 emacsOdVut8 drwx------ 2 root root 4.0k Jan 1 00:13 xdvi7GIKqr ~\/~> /sh press C-d to return to freetalk $ rm -f /tmp/xdvi7GIKqr C-d RET ~\/~>

3.14 Freetalk command - date

command: /date [arguments]

This command displays the system date. Try ‘--help’ for complete list of arguments.

3.15 Freetalk command - who

command: /who

This command displays the buddy list as well as their current buddy status.

Example:

~\/~ /who * abindian@gmail.com (ab) twistedlogix@gmail.com * tejasvk@gmail.com -> [Away] (on metarnity leave) basavanagowda@gmail.com amarts@gmail.com (ts3) ~\/~

3.16 Freetalk command - status

command: /status [online|away|chat|xa|dnd] [MESSAGE]

Sets or displays your current status.

Example:

~\/~ /status online Using Freetalk ~\/~ /status Current status: online Using Freetalk ~\/~

3.17 Freetalk command - whoami

command: /whoami

This command displays the currently logged in buddy info.

Example:

~\/~ /whoami ~\/~ /whoami Jabber ID: avati@zresearch.com Jabber Server: jabber.org Status: hacking ~\/~

3.18 Freetalk command - version

command: /version

This command displays the version information of the installed freetalk package.

Example:

~\/~ /version freetalk (Freetalk) 3.2 Copyright (C) 2005, 2007 FreeTalk Core Team … ~\/~

3.19 Freetalk command - logout

command: /logout

This command works same as /disconnect but looks more meaningfull.

Example:

~\/~ /logout Disconnected from server, reason(0): User request ~\/~

3.20 Freetalk command - history

command: /history [BUDDY]

This command displays paginated history with BUDDY. If BUDDY is not specified, it displays paginated history of only the current session.

Example:

~\/~ /history ranju1111@gmail.com Prints the history of messages with ranju1111@gmail.com paginated by less. ~\/~ /history Prints this history of messages of the current session. ~\/~

3.21 Freetalk command - load

command: /load [SCM]

This command loads the Scheme Extension file and executes it. SCM is the extension Scheme file written in Guile. This command helps for the better customization of the software.

SCM is first looked for in the current directory, followed by ~/.freetalk/extensions followed by the global prefix/share/freetalk/extensions.

SCM can also be an absolute path.

Example:

~\/~ /load beep.scm ~\/~

3.22 Freetalk command - setup

command: /setup

This command prepares a fresh ‘~/.freetalk’ directory with backing up the older one.

Example:

~\/~> /setup '/root/.freetalk' -> '/root/.freetalk-backup-0' Creating fresh state /root/.freetalk NOTE: Archieved previous state to /root/.freetalk-backup-0 !!! ~\/~>

3.23 Freetalk command - login

command: /login

This command is the better interactive login than the normal login. This command should be followed by /disconnect if you are logged in.

Example:

~\/~ /login Jabber ID: harshavardhanacool@gmail.com Password: Enable TLS/SSL (Y/N)? [Y]: y Port [5223]: 2401 Connecting... ~\/~

3.24 Freetalk command - help

command: /help [freetalk-command]

This command prints help information on freetalk-command commands interatively in a sorted way.If no argument in given it prints the help for all the commands.

Example:

~\/~ /help /history /history - /history [BUDDY] Display history page by page ~\/~

3.25 Freetalk command - repl

command: /repl

This command helps in debugging. Invokes the guile interpreter resulting in the better debugging of the freetalk Scheme extension.

Example:

~\/~ /repl guile>(define ft-get-jid "anonymous@yourchoice.com")

3.26 Freetalk command - urlview

command: /urlview [BUDDY]

This command helps in viewing URL's in the message archive or message coming from a particular BUDDY.More precisely this command catches URL or URL's in the message and launches the browser to open the URL.

Example:

~\/~ /urlview ksv@gmail.com ksv: http://freetalk.nongnu.org/ ~\/~

3.27 Freetalk command - freetalk

command: /freetalk BUDDY

This command helps in checking whether the other BUDDY is using freetalk or not.

Example:

~\/~ /freetalk maxcohen@gmail.com Yes maxcohen@gmail.com is using freetalk. ~\/~

3.28 Freetalk command - greet

command: /greet BUDDY

Send IRC style greeting message to your BUDDY.

Example: ab@jabber.org> /greet avati@jabber.org On the other side avati@jabber.org gets a message ``aaaaaavvvvvvvvvvtttttttiiiiiii''.

3.29 Freetalk command - burst

command: /burst BUDDY MESSAGE

Explode MESSAGE in to multiple charactest (IRC style greeting) and send it to BUDDY.

Example: ab@jabber.org> /burst avati@jabber.org avati On the other side avati@jabber.org gets a message ``aaaaaavvvvvvvvvvtttttttiiiiiii''.

3.30 Freetalk command - burst-of-romance

command: /burst BUDDY COUNT MESSAGE

Send COUNT number of MESSAGE to BUDDY with random delays in between. This command is useful to simulate multiple hand-made kisses.

Example: ab@jabber.org> /burst hackergirl@jabber.org 45 :-*

3.31 Freetalk command - broadcast

command: /broadcast MESSAGE

Send MESSAGE to all the buddies

Example: harshavardhana@jabber.org> /broadcast "Hello All, I am back"

3.32 Freetalk command - proxyserver

command: /proxyserver [proxyservername]

Specify the proxyservername which you want to connect, or display the currently set proxyserver.

~\/~ /proxyserver Current ProxyServer: ~\/~ /proxyserver tc.vip.org ~\/~ /proxyserver Current ProxyServer: tc.vip.org ~\/~

3.33 Freetalk command - proxyport

command: /proxyport [proxyport]

/proxyport command sets the specified TCP proxyport to be used for the next /connect or display the currently set proxyport

~\/~ /proxyport Current Port (8080 = default): 0 ~\/~ ~\/~ /proxyport 8080 ~\/~ /proxyport Current Port (8080 = default): 8080

4. Customizing freetalk

freetalk can be customized to a great extent using Guile interface. User can herself/himself customize or extend new features in freetalk using Scheme as extension language. Most of the features are already written in Scheme.

If you want to extend freetalk yourself, you can further explore freetalk Extension Developer Guide. (see section Extension language)

4.1 freetalk.scm

Freetalk loads the startup options from ‘~/.freetalk/freetalk.scm’. Right from custom settings like username, password … to complete Scheme programming can be done in this file.

;; Sample ~/.freetalk/freetalk.scm
;; It sets connection parameters and tries to connect on
;; starting freetalk
(and (strings=? (ft-get-jid) "")
                (ft-set-jid! "avati@jabber.org")
                (ft-set-password! "f00b4r")
                (ft-set-sslconn! 1)
                (ft-set-server! "jabber.org")
                ;; Proxy support
                (ft-set-proxyserver! "your.proxy.org")
                (ft-set-proxyport! "8080"))

All entries in this file freetalk.scm are optional.How ever there is no limit of cutomizing this file using Guile Interface. (see section Extension language)

4.2 init.scm

All system wide policy settings and extensions are loaded through ‘init.scm’. By default you can find ‘init.scm’ at ‘/usr/share/freetalk/extensions/’. To override this system wide ‘init.scm’ file, copy it to ‘~/.freetalk/extensions/init.scm’. You must be aware of what you are doing, before you mess up anything here.

(see section Extension language)

4.3 Default Scheme extensions

Most of the freetalk features are available through Scheme extensions. To override these extensions, copy them from ‘/usr/share/freetalk/extensions/’ to ‘~/.freetalk/extensions/’ and edit them.

(see section Extension language)

5. Tips and Tricks

You are free to use complete Readline keys inside freetalk. Frequently used Readline keys inside freetalk are,

If you want to do further stunts, jump to Readline manual, See Readline: (Readline)Readline section `Readline' in Readline.

(1)

6. Extension language

An extension language is a programming language interpreter offered by an application program, so that users can write macros or even full-fledged programs to extend the original application. Extension languages have a C interface (it is usually C, but it could be any other compiled language), and can be given access to the C data structures. Likewise, there are C routines to access the extension language data structures.

This uses GNU extension language - Guile (which can stand for _GNU Ubiquitous Intelligent Language Extension_). Guile started out as an embeddable Scheme interpreter, and has rapidly evolved into a kitchen-sink package including a standalone Scheme interpreter, an embeddable Scheme interpreter, several graphics options, other languages that can be used along with Scheme (for now just _ctax_ and _Tcl_), and hooks for much more.

7. Variables

Freetalk avoids sharing of variables between C and Scheme environment. Everything is done through primitive procedures for clarity and control.

8. Procedures

The following are the list of freetalk procedures that are exported to Scheme. Now you are able to call the procedures from Scheme that are written in C.

8.1 General procedures

primitive: ft-load filepath

Loads and evaluates filepath.scm from mentioned path or from ‘~/.freetalk/extensions/’ or from ‘/usr/share/freetalk/extensions/’.

Example:

(ft-load "beep.scm")

primitive: ft-add-buddy! buddy

Adds buddy into your contact list.

Example:

(ft-add-buddy! "vikasgp386@gmail.com")

primitive: ft-get-jid jabberid

Gets jabberid from the console.

Example:

(and (string=? (ft-get-jid) "") …)

primitive: ft-set-jid! defaultid

Set defaultid as the Jabber ID to be used on the next connect.

Example:

(ft-set-jid! "anand.avati@gmail.com")

primitive: ft-get-conn-status

Gets the status of the connection from the server. 0 - Not connected. 1 - Connected, Not authenticated. 2 - Authenticated. (usable for IM)

Example:

(display (ft-get-conn-status))

primitive: ft-get-password

Gets the currently set password.

Example:

(and (string=? (ft-get-password) …)

primitive: ft-get-server

Get the servername configured for the next connection.

Example:

(and (string=? (ft-get-server) "") …)

primitive: ft-set-sslconn! boolean

Set the value such that login is in SSL mode or not.

Example:

(ft-set-sslconn! #t)

primitive: ft-send-message buddy message

Sends message to the buddy.

Example:

(ft-send-message "abindian@gmail.com" "had breakfast? or was it lunch?")

primitive: ft-display message

Prints the message in the console. Unlike the display primitive, this procedure takes care of printing message asynchronously keeping the readline state as-is.

Example:

(ft-display ("I am proud of freetalk"))

primitive: ft-bind-to-ctrl-key char command

Binds CTRL+ given char to arbitrary scm command. Allows for displaying roster or whatever by just pressing a key even during composition of new messages, keeping the readline state as-is.

Example:

(ft-bind-to-ctrl-key #\a "(/who \"all\")")

8.2 Configuration procedures

8.3 Hook related procedures

@footnote { Info awaiting coming soon....

primitive: ft-hook-return

Makes the calling procedure return immediately after running the hooks.

Example:

8.4 Utility procedures

These are general purpose utility procedures written completly in Scheme.

(2)

9. Hooks

Through Hooks facility Freetalk lets you steal its control at various important junctures during execution.

hook: ft-message-send-hook buddy message

Hook procedure is called with buddy and message as arguments on every send message operation.

Supporting primitives:

see ft-hook-return

Example:

hook: ft-message-receive-hook buddy message

Hook procedure is called with buddy and message as arguments on every receive message operation.

Supporting primitives:

see ft-hook-return

Example:

hook: ft-presence-receive-hook buddy message timestamp

Hook procedure is called with buddy, message and timestamp recieve the presence.

Supporting primitives:

see ft-hook-return

Example:

hook: ft-disconnect-hook

Supporting primitives:

see ft-hook-return

Example:

10. Learning further

The following are the URLs where you can find useful manuals for Guile and Scheme.

http://www.gnu.org/software/guile/
http://www.schemers.org/
ftp://ftp.cs.utexas.edu/pub/garbage/cs345/schintro-v14/schintro_toc.html
http://www.informatik.uni-kiel.de/~scheme/
http://freespace.virgin.net/david.drysdale/guile/tutorial.html
http://nis-www.lanl.gov/~rosalia/gnudl-doc/learn_libguile_toc.html
http://theoryx5.uwinnipeg.ca/gnu/guile/guile-user.html#SEC_Top
http://www.nada.kth.se/~mdj/guile-ref/guile-ref_toc.html
http://www.red-bean.com/guile/guile/old/3540.html
http://nis-www.lanl.gov/~rosalia/mydocs/guile-user.html
http://www.cs.utexas.edu/users/lavender/courses/scheme/
http://www.cstr.ed.ac.uk/projects/festival/manual/festival_8.html#SEC24
http://www.cs.ccu.edu.tw/~dan/tutorials.html
http://www.wcug.wwu.edu/~randyman/COMPUTERS/SCHEME/start.htm
http://www.dmoz.org/Computers/Programming/Languages/Lisp/Scheme/Teaching/
http://www.cs.caltech.edu/~cs181/doc/
http://cis.csuohio.edu/~hysockel/Links/Documents.html

11. Authors

We believe in Software Freedom and Ethics, the GNU's way.

11.1 FreeTalk Contributors (sorted alphabetically)

11.1.1 Core team

11.1.2 Documentation

11.1.3 Packaging

11.1.4 contact point

12. URLs

URL: Homepage

http://www.gnu.org/software/freetalk/

URL: Download

http://savannah.gnu.org/download/freetalk/

URL: CVS

To know project information like Bugs, Updates, Support, Patches, Tasks, News, Development Status, Activity Percentile, Project Activity visit http://www.gnu.org/software/freetalk/

URL: Mailing list

Freetalk has its own mailing list. The mailing list is for support, reporting bugs, mailing announcements. You are welcome to subscribe.

To Subscribe/Unsubscribe visit, https://savannah.gnu.org/mail/?group=freetalk.

URL: Bugs

You are welcome to send bug reports about freetalk to https://savannah.gnu.org/bugs/?group=freetalk. The bugs that you think are of the interest to the public (i.e. more people should be informed about them) can be Cc-ed to the above mailing lists.

Before actually submitting a bug report, please try to follow a few simple guidelines.

1. Please try to ascertain that the behavior you see really is a bug. If Freetalk crashes, it's a bug. If freetalk does not behave as documented, it's a bug. If things work strange, but you are not sure about the way they are supposed to work, it might well be a bug. Don't predict that there is a Bug try to find it and report.
2. Try to repeat the bug in as simple circumstances as possible.
3. Find where the bug is, fix it and send the patches. :) (see section Guidelines for submitting a patch)

Send your specific queries to Vikas Gorur vikas@zresearch.com

13. Guidelines for submitting a patch

1. Copy the latest CVS version of freetalk directory as freetalk-hack.
2. Make changes in your freetalk-hack directory.
3. Create patch using
   # diff -pruN freetalk freetalk-hack > freetalk-patch-title
4. Mail the patch file ‘freetalk-patch-title’ to the mailing list with subject prefixed with ‘PATCH:’.
   Please send only text mails with patch as a part of the message body. Don't update ‘ChangeLog’ file, instead add your comments at the beginning of the body.

14. Portability

Since freetalk uses GNU Autoconf for building and configuring, and avoids using ‘special’ ultra–mega–cool features of any particular Unix, it should compile (and work) on all common Unix flavors.

Various freetalk versions have been compiled and tested under GNU/Linux. However freetalk can be easily ported to any POSIX complaint platform with Guile and Readline ports. If you compile it on an architecture not listed here, please let us know so that we can update it. (see section URLs)

14.1 Freetalk License

Freetalk licensed under GNU General Public License v3 or later.

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

14.1.1 Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software—to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”.

   Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

   You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
   1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
   2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
   3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

   These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

   Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

   In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

4. You may copy and distribute the Program (or a work based on