module: rs
docs: |
  Provides operations over result-sets, or commands which return result-sets.
symbols:
  - name: new
    syntax: rs:new [-table TABLE]
    docs: |
      Creates a new, empty result-set. If -table is specific, will configure the result-set table to
      that of TABLE. Otherwise, the result-set will inherit the current table.
  - name: query
    syntax: rs:query EXPRESSION [ARGUMENTS] [-table TABLE]
    docs: |
      Invokes a query expression and returns the result as a result-set. The query can be invoked with
      ARGUMENTS, which must be a dictionary with key/value pairs that are made available to the query
      as either attribute placeholders (`:attr`), or value placeholders (`$value`).
      
      If -table is specific, will run the query over TABLE. Otherwise, the query will be invoked
      over the current table.
      
      Note that this command blocks the command thread until either the results are available, or if
      an error occurs. To avoid this, use 'async:query', which will run the query in the background.
    example: |
      results = rs:query 'pk = $myID' [myID:"abc132"] -table users
  - name: scan
    syntax: rs:scan [-table TABLE]
    docs: |
      Runs a table scan, returning the first page of results as a result-set. If -table is specific, will
      run the scan over TABLE. Otherwise, the scan will be over the current table.
  - name: next-page
    syntax: rs:next-page RESULTSET
    docs: |
      Runs the next page of results from the passed in result-set. This will depend on how RESULTSET was
      created. For example, if RESULTSET was from a query, this will return the next page of results from that
      query. Likewise, for scans.
      
      If the next page is available, the results will be returned as a new result-set, leaving the original result-set
      unmodified. If no next page is available, then nil will be returned.