Roost Basic

Roost Basic is Roost's shell-style language: ordinary Roost command lines, plus variables, if, loops and functions. It's the default.

Scripts

script new tidy opens the editor. Each line is a command or a statement. # starts a comment (at the start of a line, or after a space, so #rust isn't one). End a line with \ to carry on on the next. Save with Ctrl S, then run it by typing its name.

# morning: open my usual sites in a group
open mail.example cal.example news.example | group Morning --color blue
notify "Good morning"

Lines run in order and the script stops at the first one that fails (unless it's inside try).

Variables

set n = 3
set name = "bats"
set sites = ["a.example", "b.example"]
set yt = $(tabs --site youtube.com)
print $n
print $yt.count

• $name uses a variable. Lists and tabs have fields: $tab.title, .url, .site, .number, .pinned; lists have .count.
• $last holds what the last command found.
• vars lists your variables; unset name removes one.

Script words

Words after a script's name go to the script as $1 to $9, and $args holds them all. Words you don't give are empty.

# pick: pin every tab from a site
#   pick youtube.com
if $1 == ""
  fail "Which site? Like: pick youtube.com"
end
tabs --site $1 | pin --yes
print "Pinned $1 ($args.count words given)"

run pick youtube.com works too. In a script, write \$5 for a dollar sign; $9.50 stays as it is.

Memory between runs

remember name value keeps a value for the next time the script runs; recall("name", default) reads it back (numbers come back as numbers). Each script has its own memory, and so does the prompt.

# price-watch: tell me when the price drops
#   price-watch https://shop.example/item
open $1 --here
wait-for "$"
set now = number(read(".price"))
set before = recall("price", 0)
if $before > 0 and $now < $before
  notify "Price dropped from $before to $now"
end
remember price $now

• remember on its own lists what's saved; remember price --rm forgets one; remember --clear forgets all of them.
• At the prompt, recall price shows a value.
• Up to 50 values per script, 2,000 characters each. Deleting a script forgets its memory.
• Nothing is remembered from private or Vampire Bat windows, and scripts from Echo or .roost files can't use memory.

Text and quotes

In "double quotes", variables and $( … ) are filled in. In 'single quotes' text stays exactly as typed.

print "Found $n tabs on $(url)"
print 'costs $5'

Values put into commands are always quoted for you, so a page title with spaces or a | in it can't turn into another command.

Command output

$( command ) runs a command quietly and gives back what it found: a list of tabs or links, or text. $list | command pipes a variable into a command.

set bats = $(tabs | grep -i bat)
$bats | group "Bats" --color green

if

if count($bats) > 3
  $bats | group "Bats"
else if count($bats) == 0
  print "No bat tabs"
else
  print "Only a few"
end

Loops

for tab in $(tabs --unpinned)
  if $tab.title contains "bat"
    $tab | pin
  end
end

repeat 3
  scroll down
  wait 1s
end

while exists("Load more")
  click "Load more"
end

break leaves a loop, continue skips to the next round, stop ends the script, and fail "why" stops it with a message. A loop goes round at most 1,000 times.

try and catch

try
  click "Next page"
catch why
  print "No next page: $why"
  stop
end

If a line between try and catch fails, the lines after catch run, with the reason in $error (or the name you give). Without catch, a failed line is just skipped. Ctrl C, answering no to a question, and the safety limits can't be caught.

Comparing and combining

See Functions for count(), has(), hour() and the rest.

At the prompt

At the Roost prompt you can use set, print, vars, unset and $variables one line at a time. Blocks (if, loops, try) work in scripts.

roost:~$ set yt = $(tabs --site youtube.com)
roost:~$ print $yt.count
3
roost:~$ $yt | mute
Muted 3 tabs.

A full example

# tidy: close old YouTube tabs, group the bat tabs
tabs --site youtube.com --older 3d | close
set bats = $(tabs | grep -i bat)
if count($bats) > 1
  $bats | group "Bats" --color green
end
print "Done: ${tabcount()} tabs left"