### ----------------------------------------------------
### -- TOP
### -- Licenses: Artistic-2.0
### -- Authors: Tim Nelson
### -- File: docs/Text/Reference/TOP.txt
### ----------------------------------------------------
NAME
Raku TOP - Table Oriented Programming in Raku

AUTHOR
Tim Nelson - https://github.com/wayland

TITLE
Raku TOP

SUBTITLE
Table Oriented Programming in Raku

TOP::Core

    role	TOP::Core {...}



This is the common code that's shared across all TOP objects; this is
intended to be a role on all TOP classes.

method load-library

method load-library(Str :$type = 'Database::Storage::Memory',
*%parameters)

Loads the library in question, and makes an object of the named type

Tuple

    class	Tuple is Hash::Ordered {}

This is the Tuple class from which all other Tuple classes descend.

It's descended from Hash::Ordered because the columns may well need to be
ordered. In the case of SQL, it's less important, but in the case of a
spreadsheet, it's important.

Field

    class Field does Positional ...

This class represents a field/column in a Relation. It can be read
positionally, but should also know and store other relevant attributes
about the field. Fields should generally have a name; in an SQL-like
setting, it's the actual field name, and in a spreadsheet-like setting, it
should generally be the column label (A, B, etc), unless specified
otherwise.

The elements in the Field can be accessed positionally. So $field[0]
returns the value for this field for the zeroth record/row.

  Attributes

Str $.name
The Field name.

  Methods

    .new

Creates a new Field.

    .new(Relation :$relation, Any:U $type)

Relation :$relation
The Relation which contains the field. Required.

Any:U :$type
The Field type. Optional. Just pass in the actual type (eg. Str -- no
quotes needed). See also .type method, below.

    type

    method 	type(Any:U $value = Nil)

Parameters:

  * Any:U $value = Nil

This method will:

  * Lets you store a type (like the $type parameter to .new)

  * Attempts to deduce a type from the existing data

Here's how it works:

  * If a type is passed in, it will be set as the type of the Field

  * If the type (new or existing) is not Nil, it will be returned

  * If the type is Nil, but there are elements in the Field, it will attempt to
  deduce the correct type

  * Otherwise, it returns Nil

The process for deducing types is to call (list).are() on the list of
values that are present in the field.

Relation

    role	Relation is SetHash does TOP::Core does Associative does Positional {}

The Relation class' main function at this point is to be composed int the
Table class; at some point there will also be a View class, at which point
it will become more relevant.

Table

    class	Table does Relation is export {

The Table class is one of the main drivers of TOP. It represents the
various storage table classes to the Raku language, so that they can all be
accessed via the same API.

  Attributes

$.storage-object


Holds the storage object (Table::Storage::Postgres, Table::Storage::Memory,
etc) that talks to the table in its backend store; the translation layer
between Table and the datastore.

Str $.name


The table name.

  Methods

    .new

Creates a new Table.

    .new(Database :$database, Str :$storage-type = 'Memory', Str :$action = 'use')

Database :$database


The database to which this table should be attached.

Str :$storage-type = 'Memory';


The name of the Storage to use when creating this table. The default is
that it's an in-memory table.

Str :$action = 'use'


What kind of action to take when creating the table.

  action      definition              Error if  Will alter  Fields
  create      force create            Present   No          Yes
  alter       alter existing          Absent    Yes         Yes
  use         no creation             Absent    No          No
  can-create  create if not existing  No        No          If Absent
  ensure      create or alter         No        Yes         If not conformant


    grep

Implements grep on Relation. 

    select(@fields, :$destination-table)

Creates a new table with only a selection of columns, not all of them

Recognises a lone '*' as a request for all fields

If $destination-table is provided, then that's used as a basis for the new
table, otherwise one is just created

    .add-row(@fields)

Can be used to add a row to a table. This is mainly for internal use by eg.
Parsers and Formatters

Database

    class	Database {...}

This is the Database class from which all other Database classes descend.

  Attributes

$.storage-object


The storage object that talks to the data store for us.

  Methods

    .new

Creates a new Database (ie. database object -- may be attaching to an
existing database)

    .new(Str $.storage-type = 'Memory')

Parameters to .new are:

Str $.storage-type = 'Memory'


The Storage that will be used by this database. The default is that it's
the in-memory Storage.

    method useTable

    method	useTable(:$name)

Creates and returns an object representing the named table in this
database.


