Downloading this old TTYtter, change log, bug list, etc.

I strongly and totally politely and not a bit hostilely suggest that you read this whole page, particularly the FAQs, before running TTYtter.

*** Remember, this is version 0.9.12! If you want the latest TTYtter, visit the main page.

Frequently asked questions (read first! before you download!)

• What are those *** warning: timeout or no data messages? Is TTYtter really that flaky?

  Those messages are informational only, and reflect network conditions. If Twitter is having problems, or your network is down, you will see these. These are non-fatal messages.

  Similarly, messages like *** JSON warning: connection cut or *** JSON warning: null list are problems with the data received from Twitter, not TTYtter, normally that the JSON is incomplete or not properly parseable. TTYtter will automatically refetch until it gets something it can use.

  The reason these messages are printed is so you can see immediately why tweets aren't being fetched or posted.

• TTYtter is killing my rate limit (I get messages saying I'm over the allowed requests per hour).

  By default, assuming normal usage, TTYtter is designed to use no more than 50% of the declared rate limit for fetching tweets and DMs. Posting DMs and tweets do not count against your limit. If you're running over the rate limit, check the following:

  • Are you using automatic rate control (i.e., -pause=auto, the default)? This is designed to take into account how often you want direct messages, along with querying the server to see how much activity Twitter is allowing. Unless you have a good reason, use automatic rate limiting -- it's good for you and it's good for Twitter.

  • If, however, you are using fixed time intervals for -pause and/or -dmpause anyway, make sure the effective total does not exceed the posted rate limit or that the intervals aren't set too low (i.e., to frequently request new tweets). Setting -pause to 60, for example, makes TTYtter fetch every minute, meaning you're up to 60 requests an hour without anything else running. Although TTYtter warns you when the rate limit changes, you may also want to check the Twitter status tumblr.

  • Are you using your Twitter username and password in another application? Many people accidentally leave ttytter running at home and then ssh in from work, starting two sessions (don't ask how many times I've done this). Also, if you have widgets or other applets that use your username and password to fetch tweets, these will also count against your rate limit, and if you have ttytter running a cron job that isn't -anonymous, that will count too.

  • Be aware of what impact your commands have. Refreshing your timeline or DM box manually is another hit, and commands like /replies, /again are a hit each, and /whois is three hits to do the friendship queries (so /wagain is four). If you don't understand what impact your usage habit has, consider using ttytter -verbose so you can see exactly what is occurring behind the scenes.

• Unicode characters look like garbage. or, I can't enter UTF-8 characters properly.

  See the section on TTYtter and UTF-8 support.

• TTYtter keeps saying my UTF-8 tweet is too long.

  The Twitter API currently does not reliably accept tweets over 140 bytes. Even if your UTF-8 tweet is 140 characters, it may expand to greater than that length in bytes, and because Twitter may behave unexpectedly with these longer tweets, TTYtter doesn't accept them for safety reasons. For more on this, see the section on TTYtter and UTF-8 support.

  If this really bugs you, a workaround is to use -autosplit=char so that TTYtter will automatically chop up your tweets into the proper length for you. See Command-line options.

• I keep fatfingering my tweets!

  Look at the -verify and -slowpost options.

• How do I turn ANSI on?

  Use -ansi, or put ansi=1 in your .ttytterrc. See Command-line options.

• How do I encrypt my session?

  See the section on TTYtter and SSL.

• How do I run my session with readline, or under a client like ssfe or screen?

  See the sections on TTYtter and readline and custom environments.

• Can I do groups or lists in TTYtter?

  There is a TTYtter extension by the awesome @vkoser to enable groups support. Get it from his blog, along with his other TTYtter hacks.

  Lists are planned for a version of TTYtter in the very near future.

Other notes

• Are you using automatic version checking with -vcheck? You should be!
• ttytter knows nothing of proxies and depends on curl or Lynx to do that. You can set your own options in each program's respective configuration file. ttytter will override certain headers and timeouts, but will not override proxy or security settings, so make sure they are correct.
• Old versions of Lynx that send incorrect Accept-Encoding: headers will spit out binary data (essentially failing to decompress the response from Twitter) and cause TTYtter to panic. At least 2.8.5rel1 or 2.8.6 is required to avoid this.
• Apart from ANSI colours and attributes, ttytter does not take advantage of any special terminal features or sequences. This is currently a feature of omission so that even the dumbest of dumb terminals can use it, but get used to updates interrupting your typing (just keep typing, it's still there). MUDders will not bat an eye at this.
• Entities like \r \n are intentionally not turned into newlines to avoid scrollspam on small screens. If you really don't like this, use -newline.
• Similarly, a lot of the Twitter metadata is thrown away right now, either because it has no relevance in a text oeuvre, or it makes the screen even more cluttered and dense.
• Search results can't be threaded currently because the Search API does not provide in-reply-to information. Once it does, this should "just work."
• Due to the arbitrary syntax possible with /set tquery and /search, it is not possible to do highlighting within hits generated by those commands.
• Lynx users may find that not all errors are caught correctly. For example, when using Lynx as the user-agent and querying a username with /again or /whois, if you query a protected username that you do not have access to, you may get a "no data" error instead of the expected "no permission" message. This is a quirk of Lynx when handling requests that fail authentication or generate errors, and can't be worked around easily. curl does not have this problem. This does not damage your data in any way.
• Where's the JSON interpreter? There isn't one and I'm not using any of the current JSON-oriented modules -- the Perl interpreter itself is doing the heavy lifting for us. Read the &grabjson subroutine to see how this works. There is some token code to prevent malicious servers from being allowed to embed arbitrary Perl in the returned JSON, but just the same, connect to trusted Twitter sources only (using -url or the defaults).

Download and change-log

• ttytter 0.9.12 (Perl script text; 93KiB)

• Old versions (warning: buggy!; not guaranteed to work with current Twitter API; use at your own risk)

ttytter has been tested against Perl 5.0050x running on AIX with Lynx 2.8.6, Perl 5.8.6 running on Mac OS X 10.4.11 with curl 7.16.3, Perl 5.6.1, 5.8.8 and 5.10.0 running on NetBSD/macppc with Lynx 2.8.5, and Perl 5.10.0 on Knoppix and Perl 5.8.8 running on the OLPC XO-1 with curl, connecting both directly and through an HTTP proxy (configured for Lynx/curl). It is guaranteed to make Larry Wall nauseous just looking at it. There are also successful reports from users of Cygwin.

Changes in version 0.9.12 (bug fixes and critical improvements only; these fixes are also in 1.0.0 final):

• If you /troff on a keyword set that has quoted phrases, the quotes get lost off all of them. Fixed.
• Restoring from /set tquery 0 also fouls up quoted search terms. Fixed.
• Setting $tquery in an extension's initialization does not override $track. Fixed. (thanks @colindean)

• Warn the user if a notification framework was selected but no notifies were requested. This might be useful for an extension to dynamically control, so it is not a fatal error.
• Another try at properly handling GeoAPI information (thanks @chfrank_cgn).
• Author breaks 50,000 tweets. A loud sobbing noise can be heard from Twitter corporate headquarters throughout most of the Bay Area.

  Although the numeric user ID bug in 1.0.0 beta also affects 0.9, it requires a change that breaks backwards compatibility, so it will not be fixed in 0.9.

• If the foreground process exits abnormally, it should still clean up the background process.
• -script and -verbose should work together better (a more effective fix is in the 1.0.0 beta).
• The -slowpost prompt lagged the signal switch ever so slightly, meaning you could hit ^C and kill the process even when it told you it was okay. The prompt is now delayed until after the signal handler change.
• -notifytype=0 should work fully now.
• -script and -status now correctly ignore -slowpost and -verify.
• /vreply format tweaked slightly.

• Tweets with geolocation information no longer cause the JSON parser to panic.
• If -autosplit=word fails, fall back on =char instead of completely destroying the tweet.
• /vre no longer threads the reply, as API changes have caused threaded tweets to be only visible to the one replied to.
• The planned conversion of 140 bytes to 140 characters as the tweet length could not be implemented in this version as the Twitter API does not correctly accept them yet.

• Identica fixes: base URL returned to friends_timeline; fixed the "null list" warnings Identica users were getting; updated JSON parser to understand the new Identica fields.
• You can now say -notifytype=0 on the command line to disable a notifytype in your .ttytterrc.
• -hold can potentially loop forever even if you don't want it to. -hold=1 or -hold by itself keeps the old behaviour, but specifying an argument greater than 1 causes the script to stop after that many unsuccessful tries. In 1.0.0, this will be changed again.
• Auto-ratelimiting changed to use 50% instead of 60%. This slightly diminishes responsiveness, but seems to help people who were getting beaten up by other client usage. You can still use -pause with an argument, of course.
• /[ef]rt no longer thread retweets to the source tweet. Per Twitter, this won't work right any more and actually prevents retweets from being seen (by causing them to be treated as replies).
• /whois and /wagain now recognize the new default images Twitter is using for accounts without avatars.
• -curl now works correctly again (stupid typo regression).
• Error codes fixed for command line tools.

• 0.9 is now the stable branch and bug fixes only will occur on this branch until a stable 1.0.x becomes available, after which it will be deprecated. New development will now occur on unstable 1.0 and there will be compatibility changes. More on that when 1.0.0 is released.
• New notification framework with built-in support for Growl (via growlnotify) and experimental built-in support for libnotify (via modifications to notify-send; see Galago Project trac ticket #147) using -notifytype and -notifies. Expandable via the API.
• Revised API method for dynamic classification of tweets using the $tweettype method. (The old $choosecolour method is now deprecated and trying to call its handler will generate a fatal error. It will be completely removed in 1.0.0.)
• Favourites support with /favourites, /(un)fave and /frt.
• Tweets can be dumped and their status URLs grabbed with /dump (suggested by @augmentedfourth).
• /short and /url take %URL% as default, and /whois//wagain and /dump populate it, allowing you to grab URLs from status IDs or user profiles and open them or repost them (based on a suggestion from @vkoser). As a nice side effect, /url can now open arbitrary URLs as arguments.
• "Verified Account" support for /whois and /wagain.
• -slowpost mode for people needing something gentler than -verify (like me).
• Training-wheels mode intercepts common newbie tweets like quit and help (disabled by -slowpost and -verify; I assume that if you set those then you know what you're doing).
• -filter is now dynamic and can be recompiled on the fly with /set filter.
• /vreply forces publicly visible replies (with the de facto r @ttytter A public reply. notation).
• /eretweet populates %% as well to allow editing with the conventional substitution sequences (thanks @jasonwryan).
• To facilitate this behaviour, %-sequences are now generally interpreted at the end of a line as well, not just at the beginning.
• New reserved namespaces for API modules using the $store global reference in anticipation of multi-module support in 1.0.0.
• HTTPS URLs now accepted by /short and the TAB completer in -readline.
• -olib option for one-line libraries on the command line.
• UTF-8 characters can now be scanned for by /url, although your underlying browser may not like them (for example, Mac OS X /usr/bin/open thinks they are filenames).
• Default replies URL now set to mentions.json but remains the same command line option for backwards compatibility.
• Substitutions using %-x sequences would accept arguments that were too high and simply cut off until it couldn't anymore. This is now correctly flagged as an error.
• Another crash bug removed.
• Internal code consolidation.
• Better error messages for deletions, failed substitutions, etc.

• Direct message selection, analogous to tweet selection, which also supports /delete, /url and /reply for a nice almost-orthogonal interface.
• /retweet and /eretweet, previously undocumented in 0.9.5 due to inadequate testing, are now officially supported and properly thread in-reply-to fields.
• Large internal change to subprocess management for easier future expansion, along with more changes to $authenticate. This internal reworking will continue up until the OAuth-based TTYtter, so people hacking on the core should beware.
• $choosecolour is now unstable. API programmers who are using this method should contact me, as I am planning to change the interface as part of the future notification framework.
• /track should not throw pagination errors on common or popular search terms. I disagree with the way Twitter has implemented this warning, but this version includes a workaround (thanks @johndalton).
• /ruler once again lines up properly with the prompt (thanks @vkoser, @jazzychad and others of the Brotherhood of the Ruler).
• Search results now are properly coloured in anonymous mode.
• GNU screen printed bold characters as inverse text. ANSI sequence tweaked for wider compatibility (thanks @arsatiki).
• Unicode code point 0x2028 needed to be seen as a newline, and subject to -newline (or not). Fixed.
• -noratelimit does not work when it is changed dynamically, so it is simply made a startup-option only.
• -filter didn't handle quote-wrapped arguments (thanks @augmentedfourth). Fixed.
• -wrap sometimes overindented following lines (thanks again @augmentedfourth). Fixed.
• Not all legal characters for URLs were accepted by /url. Fixed.
• /search did not call $conclude, so -filter counts got out of sync. Fixed.
• Author breaks 40,000 tweets. Twitter calls him on the phone to please stop and use Plurk or something.

• Selection of individual tweets and threading with /thread, /reply, /delete and /url, along with @ markers on tweets that are part of a thread.
• -noratelimit and -notrack to disable rate limit checks and tracking keywords, respectively, on systems that don't support them (most notably Laconi.ca/Identi.ca).
• API addition with $choosecolour.
• UTF-8 characters are now allowed in tracking keywords.
• Faster and more reliable JSON fetch and parsing method.
• Expanded /help text.
• Bogus colour warnings when using -noansi are fixed.

• Twitter Search API integration, based on initial work by @kellyterryjones, @vielmetti and @br3nda (/search, -queryurl), with hashtag integration and keyword management (/tron, /troff, /track, /#, -notimeline, -track) and trends (/trends, -trendurl), suggested by a whole bunch of people including the most esteemed @adamcurry.
• Customizable colours (-colour{prompt,dm,me,reply,warn}), another common request.
• Base API URL can now be specified for Twitter clone APIs (-apibase).
• Official API support for libraries driving commands, or wishing to make JSON fetches from services.
• Whitelisted accounts bombed with autoratelimiting. Fixed to constant value.
• @ highlighting in direct messages tended to bleed. Fixed.
• -status probably shouldn't print version check warnings. Fixed.
• Not every overlong prompt was getting wordwrapped. Fixed.

Changes in version 0.9.3:

• Automatically check that you're using the most current version, either with -vcheck at startup, or /vcheck within the client.
• New $authenticate API method makes it possible to store your credentials anywhere you darn well please, including nowhere. Now prompts for password when you don't specify. Based on code by @jcscoobyrs.
• Autosplit using the -autosplit option, suggested by @dogsbodyorg and @timtom.
• Correctly counts bytes in tweets, since Twitter counts in bytes, not characters (thanks @cyrixhero).
• Wordwrap for arbitrary screen sizes, based on a suggestion by @augmentedfourth.
• Verify individual tweets as you post them with -verify, along with simple Perl-expression-based filtering with -filter, based on suggestions by @cwage.
• Posting tweets did not show verbose information in -superverbose mode. Fixed.
• /setting superverbose should also set verbose. Fixed.

• Status changed to 'stable' fork; previously embryonic features now either fully enabled or made default.
• -rc=... option allows selection from multiple .ttytterrc files, based on a suggestion by @br3nda. Corresponding -norc option allowed to, conversely, completely disable any rc file present.
• API additions ($addaction/&defaultaddaction).
• Time ranges printed for /again user (when -timestamp is not enabled).
• /print ntabcomp to display newly added entries during this session, based on a suggestion by @augmentedfourth.
• TAB completion is now case-insensitive.
• Expanded control character filter from 0.8.6.
• All bug fixes and backouts from 0.8.6.

• Status changed to 'deprecated' fork.
• Control character filter added (backported from 0.9.x) and expanded to pre-interpret most common mistaken entries.
• Bug fixed with @ names framed with certain punctuation not getting highlighted.
• Backed out kludges for bowdlerized /whois and less efficient workaround JSON fetch.

• Large rewrite of the UTF-8 handling code, with hopefully better support on as wide a range of Perls as possible.
• /print tabcomp to display your optimized completer string in advance, based on a suggestion by @augmentedfourth.
• -newline to parse \n and \r, also suggested by @augmentedfourth.
• CTRL-C now correctly triggers the END subroutine, reported by @augmentedfourth. Yeah, he's been busy. ;-)

• Split into 'unstable' fork.
• Major retooling of program logic to eliminate redundant portions and streamline complex sections.
• Auto-ratelimit support with -pause=auto (EMBRYONIC). However, works well enough to be the default right now. If you don't want to use this, or don't trust it, you probably should be using 0.8.5.
• Support for Term::ReadLine::* with -readline (EMBRYONIC), including cursor key history and TAB completion (with auto-learn), and API support with $autocompletion/&defaultautocompletion to define your own TAB completion routine.
• URL shortening (-shorturl and /short).
• Runtime changes to certain options now supported with /set and /print.
• Support for unusual client environments, using -leader and -noprompt, based on an idea submitted by @chfrank_cgn.
• Easier SSL operations using -ssl instead of requiring changes to .ttytterrc.
• /again on a username reports the time of last update if you aren't using -timestamp.
• Friendship queries fixed.
• All bug fixes from 0.8.5.
• Author breaks 25,000 tweets. He is, truly, a nerd.

• Split into 'stable' fork.
• Bug fixed with UTF-8 handling, even on systems and Perls that don't understand UTF-8.
• Bug fixed with users with no DMs.

• Several temporary workarounds for glitches in the Twitter API, namely a kludge for eating invalid JSON generated by tweet deletes, disabling some fields in /whois that were pulled, and turning off friendship checks as they currently generate 500 errors. The tweaked JSON fetch is also marked as kludge. These temporary fixes will be backed out when they are fixed on Twitter's end.

• Tweaked fetch routine pending eventual format of null responses (i.e., much less spurious timeout or no data messages).

• Twitterer names, and @ names, are now boldface and underline respectively based on patches submitted by @smb.
• Expanded /whois with code for looking up friendships, and processing avatar images (-avatar, -frurl).
• API additions ($precommand, $prepost, $postpost).
• Certain HTTP status codes could cause the JSON parser to freak out. Fixed.
• -noansi didn't take precedence over -ansi like it was supposed to. Fixed.

• $lasttwit, and origination classes for $handle, both API enhancements suggested by @emilsit.
• -lynx and -curl can be told to run a specific binary, useful for PATH-deficient environments or version testing.
• -status correctly warns for tweets over 140 characters.
• Speaking of which, normal tweet activity also has better warning text for oversize tweets too.
• Additional debugging information for failed test logins available.

• Robust scripting support for simple command-line queries (/end and -script).
• -pause=0 is now valid.
• Popping words off the end of the line (%%--, etc.) works.
• API additions (&standardtweet, &standarddm, DUPSTDOUT).
• Null array references could escape from certain asynchronous commands and cause uncaught exceptions. Fixed.
• &prinput allegedly took arguments, but ignored them and just used $_ like it used to. Kludged around.

• Null array references could leak from the JSON parser, which would throw an uncaught Perl error. Fixed.
• /ruler (suggested by @jspath55).

• Changes suggested and coded/adapted from code by @br3nda:
  • ANSI colour and highlighting (and -ansi/-noansi).
  • Timestamp support, including templates on supported installations (-timestamp).

• Replies support (/replies and -rurl).
• /again expanded to allow querying user timelines (and -uurl).
• API expanded with $prompt, &defaultprompt and -twarg.
• Anonymous mode (-anonymous).
• User query (/whois and /wagain, and -wurl).
• JSON parser upgrades to accomodate user queries.
• Error message reporting fixed.
• Proper detection of presence/absence of modules (particularly fixing problems with -seven) and streamlined BEGIN block.
• No need to pause with -silent.
• Several side effects have now been incorporated as virtues.
• Author breaks 10,000 tweets. What a dweeb he must be.

• Improved stability in JSON validator when using Lynx as the user-agent.

• Direct message support added to both interactive client and API, with -dmurl and -dmpause.
• -silent mode and exit statuses.
• Abstraction of console input processing to facilitate future expansion in both API and internal code.
• Recognizes new-format Twitter error messages. (Correspondingly, some API exception codes are now deprecated; see documentation.)
• Command abbreviations.
• Expanded command history support and -maxhist.
• Reworked error messages.
• Various custodial fixes and upgrades to JSON interpreter.

• Patched for various entities in the new Twitter JSON release. This version will correctly handle both ampersand-escaped and standard entities and quotes.

• Support for rate-limited API, in two ways: first, increasing default timeout to 120 seconds, and two, properly recognizing when rate-limiting has kicked in.
• Stability improvement in JSON validator.
• Additional API exception codes for the above features.
• select() loop tightened up to make timeline hits as minimal as possible.

• UTF-8 now works right (most of the time). Added -seven option for backwards compatibility.
• First support for the TTYtter API and the -lib option.
• Detached mode using -daemon, allowing bot building.
• Tweaks to defaults.
• Work-around for out-of-order tweets "stuttering" or getting stuck. This is technically a Twitter bug, but this version can now ignore the anomaly.

• Even bigger morer robuster JSON validator.
• Posting from the command line using -status.
• Can now configure update source using -update, allowing complete abstraction of TTYtter assuming the other side supports the Twitter API over JSON.
• -hold timeout tweaked.
• Messages tweaked for accuracy and semi-user-friendliness.

• Improved detection of Twitter HTML status messages and better tolerance of partially-transmitted data (which could sometimes cause ttytter's JSON validator to freak out).
• Added "re-tweet" facility for ... retweeting.
• Added -hold option.
• Another hal-fassed attempt at better UTF-8 handling.
• Exit statuses of curl/Lynx sessions are properly reported.
• Proper command line precedence over default options.