LOOP
Prev | Functional Data Manipulation Language (FDML) | Next

## Name

LOOP — Extension to Common Lisp `Loop` to iterate over all the tuples of a query via a loop clause.Loop Clause

## Syntax

    {as | for} var [type-spec] being {each | the} {record | records | tuple | tuples} {in | of} query [from database]

## Arguments and Values

`var`

  A `d-var-spec`, as defined in the grammar for `loop`-clauses in the ANSI Standard for Common Lisp. This allows for the usual loop-style destructuring.

`type-spec`

  An optional `type-spec` either simple or destructured, as defined in the grammar for `loop`-clauses in the ANSI Standard for Common Lisp.

`query`

  An sql expression that represents an SQL query which is expected to return a (possibly empty) result set, where each tuple has as many attributes as `function` takes arguments.

`database`

  An optional database object. This will default to the value of *default-database*.

## Description

This clause is an iteration driver for `loop`, that binds the given variable (possibly destructured) to the consecutive tuples (which are represented as lists of attribute values) in the result set returned by executing the SQL `query` expression on the `database` specified.

`query` may be an object query (i.e., the selection arguments refer to View Classes), in which case the supplied variable is bound to the tuples of View Class instances returned by the object oriented query.

## Examples

    (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
    "My database"
    => *MY-DB*
    (loop with time-graph = (make-hash-table :test #'equal)
       with event-graph = (make-hash-table :test #'equal)
       for (time event) being the tuples of "select time,event from log"
       from *my-db*
       do
         (incf (gethash time time-graph 0))
         (incf (gethash event event-graph 0))
       finally
         (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
           (format t "~&Time-Graph:~%===========~%")
           (maphash #'show-graph time-graph)
           (format t "~&~%Event-Graph:~%============~%")
           (maphash #'show-graph event-graph))
         (return (values time-graph event-graph)))
    >> Time-Graph:
    >> ===========
    >> D                                        => 53000
    >> X                                        =>     3
    >> test-me                                  =>  3000
    >>
    >> Event-Graph:
    >> ============
    >> CLOS Benchmark entry.                    =>  9000
    >> Demo Text...                             =>     3
    >> doit-text                                =>  3000
    >> C    Benchmark entry.                    => 12000
    >> CLOS Benchmark entry                     => 32000
    => #<EQUAL hash table, 3 entries {48350A1D}>
    => #<EQUAL hash table, 5 entries {48350FCD}>

    (loop for (forename surname)
          being each tuple in
            [select [first-name] [last-name] :from [employee]
                    :order-by [last-name]]
          collect (concatenate 'string forename " " surname))
    => ("Yuri Andropov" "Leonid Brezhnev" "Konstantin Chernenko" "Mikhail Gorbachev"
        "Nikita Kruschev" "Vladimir Lenin" "Vladimir Putin" "Josef Stalin"
        "Leon Trotsky" "Boris Yeltsin")

    (loop for (e) being the records in
         [select 'employee :where [< [emplid] 4] :order-by [emplid]]
      collect (slot-value e 'last-name))
    => ("Lenin" "Stalin" "Trotsky")

## Side Effects

Whatever effects the execution of the SQL query has on the underlying database, if any.

## Affected by

None.

## Exceptional Situations

If the execution of the SQL query leads to any errors, an error of type sql-database-error is signalled.

Otherwise, any of the exceptional situations of `loop` applies.

## See Also

`query`
`map-query`
`do-query`
`print-query`
`select`

## Notes

The `database` loop keyword is a CLSQL extension.

The extended `loop` syntax is common across the functional and object-oriented data manipulation languages.

Prev | Up | Next
DO-QUERY | Home | MAP-QUERY