diff --git a/README.md b/README.md index 6b7e022..2ebdfd6 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,102 @@ forthlift — post sequences of texts on social media =================================================== -Forthlift is a command line application to post sequences of text lines on social media. +Forthlift's primary use case is a command line application to post sequences of +text items on social media. You first prepare your thread in your text editor, +then call forthlift, and everything is posted at once. -Its main use case is to post on Twitter several status that you have prepared first in your text editor. +As side effect, fothlift became a more generic tool, that can process text +streams, format them, assemble their atomic units in anothers, and then send +them elsewhere. It is thus designed to ease automation and integration with +existing tools, and has an Unix-like text-and-pipes philosophy. -It is thus designed to ease automation and integration in existing tools -and had an Unix-like text-and-pipes command line interface. +## Examples -For example, it makes it easy to post "chained" twitter status (that answer to each others) -from your text editor. Just send the selected text to its standard input, selecting the -twitter API, and voilà. Using Vim, you can tweet the visually-selected lines with: -`:'<,'>w !forthlift -a twitter` +### Select in Vim, post on Mastodon + +Forthlift makes it easy to post "chained" Mastodon toots +(that answer to each others) from your text editor. +Just send the selected text to its standard input, selecting the +twitter API, and voilà. + +Using Vim, you can toot the visually-selected lines (each line making a toot) +with: +```vim +:'<,'>w !forthlift --lift mastodon +``` + +### Prepare toots in a file, post on Mastodon + +Let's say that you prepared a text file of the form: + +``` +This is a multi-lines... + +... toot! +-- +And here is an answeer to the previous toot. +(With two lines as well.) +-- +And a final toot. +``` + +You would want the toots to show a counter, managing the expectations of your +reader. + +You can post it right away with: +```sh +cat my_file.txt | forthlift --consume "sections:--,skip" --format counter -l mastodon +``` + +### Manage long threads from Markdown + +Let's say you want to post the sections of this README as a sequence of toots, +with a hashtag that indicates it's gona be long. +And you would want to double-check what it would do first. You can send the +items on the standard output, like: + +```sh +forthlift -s filename:README.md -c sections -f suffix:#longThread -f panel -l stdout +``` -## SYNOPSIS +### Full-featured file-to-Mastodon pipeline -`forthlift` [-h] - -`forthlift` [-a {stdout,twitter}] [-m MAXLEN] [-i|-t] [-c] [-q] [-d] [-s] +```sh +# Define a shortcut +mastopost() { forthlift -s "filename:$1" -c sections:^#,skip -f skip -f counter -f suffix:#longThread -l mastodon; } +# Call it with: +mastopost my_file.txt +``` ## DESCRIPTION ### A generic tool -Generally speaking, it's a Unix-like command that operate a sequence of pre-programmed -chained actions on its text input. +Generally speaking, Forthlift is a Unix-like command that operate a sequence of +pre-programmed chained actions on its text input. -It comes with some existing actions: -* `stdout`: print the input text on the standard output, -* `twitter`: send the input text as status on twitter. +Forthlift has four action operators classes, one for each step of the processing: + +1. `stream`, indicating from where to get the input data. +2. `consume`, telling *how* to parse the data from the input stream. +3. `format`, for manipulating the content itself. +4. `lift`, defining where to send the final items. + +Only one `consume` operator can be passed, but any number of `stream`, `format`, +and `lift` operators can be combined. +To apply several operators of the same class, the user must pass the same flag +several time. For instance: + +```sh +# Applies strip, then skip, then counter on the consumed lines. +forthlift --format strip --format skip --format counter +``` + +Most of the time, the order of the operators matters. -### Features - -The main feature of forthlift is its ability to *chain* actions. -Depending on the chosen API, this could means different things: - -* for twitter, this mean that the sequence of status will be posted - as a sequence of *answers* and not as a list of independent tweets. - -* for the "stdout" API, this means that each printed line will start - with its index in the input list. - - -While it is recommended to prepare the input text with other text-processing tools -(fold, fmt, tr, sed, grep, your text editor, etc.), -forthlift comes with some rough text-processing capabilities, among which: - -* ignore or trim lines that are longer than a given size (see `--trim` and `--ignore`), - -* add a counter of the form `/` at the end of the lines (see `--counter`). - - -## OPTIONS - -* -h, --help: show this help message and exit - -* -a {stdout,twitter}, --api {stdout,twitter}: Name of the API to use. - (default: stdout) - -* -m MAXLEN, --max-len MAXLEN: Maximum number of characters in the lines. - (default: 140) - -* -i, --ignore: Ignore lines that are longer than MAXLEN (default: False) - -* -t, --trim: Trim down lines that are longer than MAXLEN. (default: False) - -* -c, --counter: Add a counter of the form " x/N" at the end of the lines, - with N being the number of lines read and x the current index of the line. - NOTE: this necessitate to read all the input before processing it. - (default: False) - -* -q, --quiet: Do not print errors and warnings on the standard error output. - (default: False) - -* -s, --setup: Setup the selected API (e.g. authenticate and get authorization to post). - (default: False) - -* -d, --independent: Post each item independently from the previous one - The behaviour of this option depends on the selected API. - For example on Twitter: do not post a line as an answer to the previous one but as a new tweet. - (default: False) - -* --twitter-images FILENAME(S) [FILENAME(S) ...]: - Upload each given image files along with the corresponding tweets in the sequence. - If there are more images than tweets, they are silently ignored. - (default: None) - - -## INSTALLATION - -### Twitter - -1) Copy `twitter.conf-dist` as `twitter.conf` and indicate your developer's API keys in the corresponding fields. -2) Run `forthlift --api twitter --setup` and follow the instructions (go to the given URL, then paste the given PIN). - -Why should you get developer's API keys? Because Twitter does not like open-source desktop applications, see: -http://arstechnica.com/security/2010/09/twitter-a-case-study-on-how-to-do-oauth-wrong/ +## SYNOPSIS +{{FORTHLIFT_HELP}} diff --git a/src/forthlift/forthlift.py b/src/forthlift/forthlift.py index c358c38..2aeccbb 100755 --- a/src/forthlift/forthlift.py +++ b/src/forthlift/forthlift.py @@ -159,7 +159,7 @@ class format: yield item class glue(Format): - """Glue consecutive items together if they are not separated by an empty one.""" + """Glue consecutive items together if they are not separated by an empty one. Make a new item after an empty one.""" def __call__(self, items): current = "" for item in items: