Texapp for Perl (Somewhat Early Alpha)

Texapp is a port of the highly arcane and inexplicably beloved TTYtter text mode client for Twitter to App.net. If you knew/loved/hated/wanted to smash @doctorlinguist in the face because of/felt strange rumblings of passion towards/used TTYtter, now you can use the same interface, most of the same commands, and pretty much all of the same awesome power for ADN.

During the Super Early Alpha-Alpha, As of 0.5.0, Texapp has progressed from Super Early Alpha-Alpha to Somewhat Early Alpha. During this time, Texapp will be offered mostly for those already familiar with TTYtter along with the freaks of nature and the typically incautious and those who love them. This document will not be a lot of help to you if you find the command line totally alien. Get used to TTYtter on that "other service" and then come back here. Most of the same stuff applies; these docs are just for the differences right now.

If you are an existing Texapp user, go to the changelog and download for What's New. If you're interested in writing Texapp extensions and ADN bots, go to our Texapp API documentation.

Setup

• If you already have TTYtter, then you already have these prerequisites. If not, look at the following:
  • Required At least Perl 5.8.6 or higher. Perl 5.6 or 5.005 might work, but have not been tested. Mac OS X 10.4+ comes with this version of Perl. Most Linux distros also include it; if not, install it with your package manager.
  • Required At least cURL 7.16 or higher, configured for SSL, with up to date root certificates. Mac OS X 10.4+ comes with cURL, but the certs might be old. Use this script to download new certificates, and copy the resulting ca-bundle.crt to /usr/share/curl/curl-ca-bundle.crt (be sure to save your old one just in case). If you use Linux or a *BSD, use your distro's package system, and you can use the same script to update your certificate bundle if you need to.

  • Optional but Strongly Recommended Term::ReadLine::TTYtter 1.4 or higher for readline support, or a compatible readline driver such as Term::ReadLine::Gnu or Term::ReadLine::Perl. Then pass -readline on the command line, or readline=1 in your ~/.texapprc (see below). Term::ReadKey may be required as a prerequisite. Both are available from CPAN.
  • Optional Growl 1.1.6 or higher is supported on OS X, using growlnotify, which is an optional install.
  • Optional notifysend on supported systems using libnotify, but you need to recompile it with this standard input patch, or you can build a whole new notifysend with this source file (compile instructions inside; full libnotify source not needed).

Running Texapp

• Download Texapp (see below), and chmod +x texapp; ./texapp
• Texapp will start the OAuth wizard and give you a URL. Cut and paste it, log in (if needed) and authorize the app, and then cut and paste the resulting bearer token back into Texapp.
• Restart Texapp and the awesome will start.
• When Texapp is running, there are at least two processes at any time: the foreground, where you enter commands, and the asynchronous background, which automatically fetches posts and talks to the API in the background. If you install Term::ReadLine::TTYtter, this is much more seamless.

What works in Texapp

• read timelines and post:
  • to post, just type and press RETURN/ENTER (anything that doesn't start with / is a post)
  • to emote, type /me followed by your emote (e.g., /me smacks @jnm, which appears to Texapp users as [<doctorlinguist> smacks @jnm]
  • defaults to global timeline. /personal and /global switch back and forth
  • to redisplay your timeline, /again (/a for short)
    • display more or fewer posts with +xx (e.g., /again +40 shows up to 40 posts from your timeline and anything mixed into it)
    • to see posts before a certain point, use <menucode (see below for what a menu code is) (e.g., /a <a0 shows posts prior to post a0) << new in 0.5.0
    • you can use them together
  • to force an update of your timeline (which occurs asynchronously every 20 seconds or so anyway), /refresh (/r for short)
  • to see mentions and replies to you, /replies (/re for short); display more or fewer posts with +xx (e.g., /re +40 shows up to 40 of your mentions); new in 0.5.0 >> display posts prior to a particular point with <menucode (see below for what a menu code is) (e.g., /re <za0 +40 shows up to forty posts prior to post za0)

• all posts have a "menu code"
  • posts in the background (generated automatically on refreshes or request from your timeline) just have two character menu codes, a simple letter and number (e.g., a5)
  • posts in the foreground (generated in response to your commands) have three character menu codes that always start with z (e.g., za5)
    • (this keeps the "namespaces" separate, i.e., no crossing the streams!)
    • menu codes wrap automatically
  • if you have a post ID, you can also use that instead of the menu code (you can get this from /dump)

• manipulate threads:
  • posts with reply-to information have @ next to the screen name
  • display the thread with /thread [menu code] (e.g., /th a5); display more or fewer posts from it with +xx (e.g., /th +40 a5 shows up to 40 posts from the thread); new in 0.5.0 >> display posts prior to a particular point with <menucode (e.g., /th <a5 +40 shows up to forty posts prior to post a5)
    • this shows all connected posts; to simply follow reply-to chains (simpler), use /replythread [menu code] (/reth for short)
  • reply to a thread:
    • /reply [menu code] [reply]: replies to the poster of that menu code and adds it to the thread (/re for short) (e.g., /re a5 dalton is so hottt)
    • /replyall [menu code] [reply]: replies to all people mentioned in that menu code and adds it to the thread (/ra for short)
    • /replyg [menu code] [reply]: adds a post to a thread with "global context" (no @'s) (/rg for short)
      • to emote a reply, use /rg and make /me the first portion of the reply, e.g., /rg a5 /me smacks @jnm)
    • /replyh [menu code] [reply]: replies to all people mentioned in that menu code, but puts the person you are responding to directly in first position "highlighted" (/rh for short)

  • subscribe/follow a thread (even people you don't follow):
    • posts from threads you subscribe to have ~ next to the screen name
    • /threadfollow [menu code]: follows the thread a post belongs to and mixes it with your timeline (/thf)
    • /threadunfollow [menu code]: stops following a thread (/thunf); /thunf all clears all threads
      • /ref /raf /rgf /rhf reply to and follow a post

• display interactions with other users:
  • display replies, stars, reposts and follow events you've received from other users with /events; display more or fewer events with +xx (e.g., /events +40 shows up to 40 of the most recent interactions with users)
    • multiple users may appear as a "single interaction"
    • interactions referencing one of your posts have a menu code corresponding to the post you made; you can then use any command on it like usual (e.g., use /thread to see their reply (and other posts) made to yours)
      • (follows don't have a menu code, since they don't have a referring post)

• work with users:
  • show a user's posts with /again [username]; display more or fewer posts with +xx (e.g., /again +40 dalton shows up to 40 of @dalton's most recent posts) (/a for short); new in 0.5.0 >> display posts prior to a particular point with <menucode (e.g., /a <a5 +40 dalton shows up to forty posts made by @dalton prior to post a5)
  • show information about a user with /whois [username] (/w for short)
    • /wa [username] shows a user's posts and information about them
  • follow and unfollow a user with /follow [username] and /unfollow [username]
  • mute and unmute a user with /mute [username] and /unmute [username]
    • display whom you've muted with /muted; display more or fewer users with +xx (e.g., /muted +40 shows up to 40 of the people you are currently muting, and if you actually do have at least that many, you're a real meaniepants)
  • block and unblock a user with /block [username] and /unblock [username] << new in 0.5.0
    • display whom you've muted with /blocked; display more or fewer users with +xx (e.g., /blocked +40 shows up to 40 of the people you are currently blocking, and if you actually do have at least that many, maybe it's not them, it's you)
  • see if a user follows you with /doesfollow [username] (/df for short)
  • lists who follows you or who you follow with /followers and /friends respectively (/fos and /frs for short); display more or fewer users with +xx (e.g., /fos +40 shows up to 40 of your most recent followers)
    • these work on users too: /fos dalton

• erase posts:
  • deleted posts appear with a status message saying they were deleted
  • /delete [menu code]: deletes your own post with that menu code

• repost and star posts:
  • starred posts have a (*x) prepended to them, where x is the number of people who have starred that post
  • star and unstar a post with /star [menu code] and /unstar [menu code]
  • list who starred a post with /starred [menu code]; display more or fewer users with +xx (e.g., /starred +40 a5 shows up to 40 of the users who starred that post)
  • list posts you starred with /stars; display more or fewer posts with +xx (e.g., /stars +40 shows up to 40 of the posts you most recently starred)
    • this works on users too: /stars +30 dalton

  • reposted posts have % next to the screen name
  • they also have an (xX) prepended to them, where X is the number of times it was reposted
  • repost a post with /repost [menu code] (/rp for short)
    • /erp loads it into your history; then post with %RP% at the beginning or end of your next post to substitute it
    • /frp reposts and stars (favourites) the post
  • list who reposted a post with /rpsof [menu code]; display more or fewer users with +xx (e.g., /rpsof +40 a5 shows up to 40 of the users who reposted that post)
  • un-repost a post by simply /deleteing your repost (you may need to pull up your own timeline to do this)

• manipulate links and entities:
  • posts with attached URL links have & next to the screen name
  • display all the links, even hidden ones, with /entities [menu code] (/ent for short)
  • open all the URLs in a post, even hidden ones, with /url [menu code]
    • you need to set urlopen (see below) to something meaningful, like lynx -dump %U
    • /url by itself opens whatever is in %URL%, which is set by /entities, /dump and /whois

• control settings:
  • /print: list all runtime-changeable variables (/p for short); /p [variable] to show a specific setting
    • NB: not all variables work or "do things" in this version of Texapp
  • /set [variable] [value]: set a runtime-changeable variable (e.g., /set ansi 1 to turn on ANSI colour)
  • /unset [variable]: clears a runtime-changeable variable
    • booleans don't need a value: /set ansi and /unset ansi "just work"
  • /add [variable] [value]: appends to a variable, adding a delimiter if necessary
  • /del [variable] [value]: removes value from a variable, removing delimiters if necessary

  • to make settings stick, put them in ~/.texapprc (see Configuration notes for an example), or whatever the current setting of -rc is
    • to save the current settings to ~/.texapprc (or whatever the current rc file is) automatically, use the /save command << new in 0.5.0
      • (the current contents of ~/.texapprc are backed up to ~/.texapprc~)

• do other neat tricks, or give up:
  • display post metadata (/dump [menu code]), such as ID, geolocation information, stars, etc.
  • flush your readline TAB completion with /flushtab back to the default << new in 0.5.0
    • /flushtab blank resets it to absolutely blank
  • check if you're up to date: /vcheck
  • destroy the world: /eval
  • quit: /quit

Channels and private messages

• display all open channels: /pmscan (no +count needed)

• create a channel to a single user: /pm [who] [what]
• create a channel to multiple users: /pmm [who] [who] [who...] -- [what]
  • (the -- is the delimiter between the list of usernames and the PM)
• /pm and /pmm are smart -- if the channel already exists, they simply reuse it; if it does not, they create a new one
• channels are immutable: you can't add more users to a channel, you must create a new one

• /thread (synonym for /pmagain, showing all posts in the channel)
• /reply (replies to all parties in the channel)
• /url (and like posts, PMs with entity links are marked with &)
• /dump
• /entities
• /delete

To thump the background process for new PMs, /pm by itself will ask for new ones (and give you a polite message if there are no new ones to read).

Running commands from your shell (using Texapp as a command line tool)

• read your replies: texapp -runcommand="/re"
• list up to 40 of your followers: texapp -runcommand="/fos +40"
• list your timeline: texapp -runcommand="/a"

• texapp -status="Stalking Dalton mercilessly."
• echo "Stalking Dalton mercilessly." | texapp -status=- (don't forget that dash)

• texapp -runcommand="/re 819562 berg is so hotttt"

Texapp-specific command line options

Texapp also introduces new specific options:

• -notco is a delightful option to remove pointless posts with t.co URLs in them from that "other service." It defaults to off.
• -personal sets your default timeline to personal instead of global. (You can still switch back and forth.)
• -noifttt filters IFTTT posts specifically, since many users just don't know how to use this otherwise innocent tool responsibly.
• -allats allows posts in your timeline from people you follow mentioning people you don't (i.e., directed posts). Meaningless in /global, of course.
• -alsopost lets you set a command to pipe the post to after it is posted to ADN, so you can, say, post to that other bird service with TTYtter at the same time. new in 0.5.0 >> Only posts without reply-to or thread information are sent to -alsopost, so you don't accidentally crosspost things that are irrelevant on other services.
• -savequit makes Texapp automatically save your settings to ~/.texapprc (or the currently specified rc file) when you quit, just like you had typed /save. This includes the state of extensions that support saving state and the state of your TAB completer. << new in 0.5.0
• -openappnettoo: by default, Texapp now suppresses mere mentions of App.net being turned into spurious links. If you love opening those links too with /url, because, I guess, you're @berg or something, then pass this option. << new in 0.5.2

• ANSI colour uses (by default) default terminal colour for people you follow or threads you've added to your timeline<< new in 0.5.0, cyan for people you don't, red for mentions, purple for server errors and yellow for your own posts.

Configuration notes

• Settings are in ~/.texapprc and your key is in ~/.texappkey, unless you use the -rc option to change it (e.g., -rc=1 uses ~/.texapprc1; specify a full path to not use the prefix).

• Here is an example RC file that turns on automatic version checking, turns on ANSI colour, turns on readline mode (by default using Term::ReadLine::TTYtter), removes t.co posts from your timeline, uses Growl to display replies, PMs and threads you subscribe to, and uses the OS X internal URL command to open URLs with /url:

  vcheck=1
  ansi=1
  readline=1
  notco=1
  notifytype=growl
  notifies=reply,pm,subthread
  urlopen=/usr/bin/open %U
  

  Remember to read the TTYtter command line options; most of them will work.

• The /save command saves the state of Texapp's settings and extensions that support it to ~/.texapprc, backing up the old version to ~/.texapprc~ (or the current RC file). If you specify -savequit (or /set savequit), this is automatically done when you quit. << new in 0.5.0

What's under construction in Texapp

• timestamps now supported in 0.4.2
• direct messaging now supported in 0.4.0
• native reposts now supported in 0.2.0
• geolocation read-only support in 0.3.1
• streaming support
• tracking and search
• automatic rate limit control (right now, Texapp uses a fixed 20 second timeout)

Writing your own bots and extensions in Texapp

What's coming to Texapp

• Complete documentation, eventually
• Hash tag searching, scheduled for 0.6.
• Stable internal API. Warning to TTYtter extension authors: the I/O system is different! Implemented in 0.5!
• Annotations, but not sure how to do this yet
• Whatever other cool stuff Dalton & co. come up with

Known bugs

• If cURL says it can't connect to ADN, or Texapp is unable to start up because of network issues, this is not a bug: your root certificates are old! Fix them! (See above)
• Three-argument /doesfollow doesn't work yet.

What's new in 0.5.2:

• Readline completion is now properly saved with -savequit in unusual preloading circumstances too. (thanks @jnm)
• Texapp no longer crashes on startup when a notifier is specified after -savequit has run once.
• Automatically opening links to app.net triggered by mere mentions is now suppressed, except if you pass -openappnettoo, and if you do, I don't know why.
• /pmscan now sorts by time in all circumstances (most recent channel activity at the bottom).
• The /re command now correctly replies to PM IDs.
• /vreply and /vra now return an error when passed a PM. (It never worked in the first place, but now it properly complains about it.)
• /ra and /rh are turned into /re (with a warning) for PMs.
• Additional commands added to the TAB completer.

• /pmagain and /thread on a PM channel no longer give illogical errors. (thanks @jnm)

• The Texapp internal API is now open for business! Write your own bots and extensions, just like for TTYtter! There are some internal differences for TTYtter extension authors to consider.
• You can save options and internal extension state (for extensions that support it) to .texapprc using /save, or use -savequit to automatically save when the client shuts down cleanly.
• For commands that support it or it's logical, you can pass a <menucode argument to get posts or DMs before a particular point: /a <ze0 dalton
• Threads you are subscribed to now have a special notify class subthread which you can pass to the notification driver. As a side effect, they all appear to be part of your timeline, even users that you don't follow.
• /block /unblock /blocked now split from /mute /unmute /muted.
• /flushtab allows you to reset your TAB user name completion.
• /print tabcomp shows the current TAB completion entries. /print otabcomp displays the optimized listening (front-weighted); /print ntabcomp displays newly added ones.
• Posting during background refresh no longer generates a spurious -- sorry, nothing to display message.
• -alsopost filters posts that are part of a thread to avoid exporting posts to that other service without context. (thanks @oj for the suggestion)
• Notifications using notify-send have a tweaked, better-scaling timeout duration.

• Stability improvements for certain Perl versions with readline support.
• Setting and changing variables sent to the background is more asynchronous.

• Repairs random quits experienced on certain Perl versions (may manifest as spurious Not a HASH reference complaints).
• Compatibility fixes for Perl 5.16.

• -timestamp option now supported again.
• Makes PM scanning sort order a bit more logical.
• Fixes an issue with channels containing usernames with underscores in them.

• Fixes prompt race condition with the refresh after a PM is posted.
• If Texapp cannot connect to ADN to get channel metadata, it simply throws away the PM since the PM can't be meaningfully interacted with anyway (instead of various unpredictable failure states depending on how complete the channel data is).

• Finally, private message and channel support!
• Emotes.
• /rh
• Internal refactoring of private fields added to ADN schemas.

• New /reth command for directly connecting posts by reply to information instead of the entire /thread
• Belt-and-suspenders approach to JSON parser based on testing with @jnm
• Bug fixed in /leave

• New /events command displays information from the Interactions API.
• New /muted command lists your muted users.
• The /entities command is now enabled to display entity links in posts, and /url will access them also.
• Initial support for retrieving geolocation information. (Setting geolocation information is coming.) Just /dump a post for the geolocation pseudofields.
• The background no longer thrashes and now simply self-terminates if the controlling console process gets killed off (thanks @mailman1175, @jmergy).
• Deleted posts are now again correctly marked as such.

• Higher-performance I/O for faster updates and to cut down on collisions from the foreground and the asynchronous background. This changes the internal API; some old TTYtter extensions may not work quite right.
• New documentation! Read this page! The internal API will be documented as soon as I think it is stable for development (next major change will be to allow saving of state).
• Thread following and unfollowing, mixed into your timeline.
• -allats allows you to see posts from people you follow to people you don't.
• /thread now can take a +count.

• /rg ("reply global") lets you reply to a post "context-free" -- it is simply threaded to that post to link them together, but includes no @ of any user, so that it appears to everyone but is still linked into the thread.
• Posting is now more responsive and you see your post come through much sooner.
• You can now reply, star, repost, etc., reposts; the reply and star and so forth will apply to the original post.
• Repost and star counts now apply to the original post, so these stats "shine through" reposts.
• If you /replyall to a repost, you reply to the original post, but the reposter is included.
• personal=1 no longer causes an error in .texapprc (thanks @jdd)
• Cancelling a post in -slowpost mode no longer generates a spurious -- sorry, nothing to display message.

• The -personal option sets the default timeline to the personal stream instead of the global stream (or personal=1 in .texapprc). You can still switch to global with /global (and back with /personal).
• If you set -alsopost to a command, the posts you make will be echoed to it. For example, crosspost to Twitter with -alsopost="ttytter -status=- -keyf=your_key_file" (or alsopost=... in .texapprc).
• The -mentions option now works properly instead of generating error messages (thanks @wildbill).

• /rpsof, allowing you to get the reposts of a post that has been reposted.

• Suppress "200" errors, which occur randomly and aren't actually errors (thanks @jmergy).

• New post classes. Users you don't follow appear in $colouralien (class alien) which defaults to cyan; users you do follow appear in $colourfollow, which defaults to "terminal default." If you don't like this, you can change it (example: -colouralien=OFF). This allows you to pick out your "peeps" from global, for example. Replies still appear in red regardless.
• Native reposts are implemented. /rp now sends a native repost, and /thread will follow a repost back to its original thread. If you want to use the old style, use /orp (or /erp if you want to load it in to history for editing). Btw, /orp now threads the repost, too.
• -noifttt implemented (or noifttt=1 in .texapprc) which does exactly what it says: anything with a source of IFTTT is filtered, even if you follow that user.
• -notco is even smarter about obvious Twitter repostings, regardless of the source.
• Two-argument /doesfollow (does user X follow you?) is implemented, but three-argument will need API support.
• Deletes appear tagged in the stream. You can't do anything with them, though, because they're deleted!
• /ruler works properly.