Ob2ss (version 0)
Head
getTableByName(string tableName)
Fetches an Ob2ss table where you can write and read objects. --- This is optional and returns a table you can call functions against like `addAppend()` or `deleteLike()`. If you call those functions on Ob2ss, they'll run on the default table. You can set the default table with `doSetDefaultTable()` if you want to simplify your code. If you do not use this function and do not use `doSetDefaultTable()` then Ob2ss will operate on a table called `default`. _Example:_ ``` Ob2ss.getTableByName('cars').addAppend(obj); ``` is the same as ``` Ob2ss.doSetDefaultTable('cars'); Ob2ss.addAppend(obj); ```
Arguments:
| Name | Type | Description |
|---|
| tableName | string | The name of the sheet to fetch. |
addAppend(object[] objects)
Adds objects to the bottom (end) of the sheet.
---
Converts the provided array of objects into rows, and adds them to the bottom of the spreadsheet. This means
they'll appear at the end of the array of all objects stored.
Arguments:
| Name | Type | Description |
|---|
| objects | object[] | An array of objects to insert into the sheet. |
getFirst(number count)
Returns one or more first ("top") objects.
---
This function will fetch and return any number of objects from the top of the sheet. For example,
`Ob2ss.getFirst(5)` will return the first 5 rows from the sheet as objects. A count parameter is not required. If
none is present, this will return the single first object.
Arguments:
| Name | Type | Description |
|---|
| count | number | [Optional] The number of top objects to return. If not supplied, the default is 1. |
Return Values:
| Type | Description |
|---|
object[] | An array of objects representing the requested rows. |
updateLike(function selector, function mutator)
Finds and changes objects in the table.
---
Changes the fields of objects found with the `selector` and applies the `mutator` to them before writing the mutator
result them back to the sheet. Objects are updated in-place and don't move. Updated fields can include new fields.
_Example:_
```
Ob2ss.getTableByName('cars').updateLike(
(car){
car.make == 'ford',
(car){
{ car.last_wash_dateDate.now(); return car; }
);
```
Arguments:
| Name | Type | Description |
|---|
| selector | function | A function callback that accepts one argument (a candidate object) and returns a boolean
indicating whether it should be selected. |
| mutator | function | A function callback that accepts one argument (an object) and returns an object to replace
it. Don't forget to return the resultant object! |
open(Spreadsheet spreadsheet)
Sets a spreadsheet as the "database".
---
An optional call to open a Google Spreadsheet as an Ob2ss database. The sheets within the database are considered
"tables".
If you do not call `open`, Ob2ss will default to the following, in order:
1. A [bound spreadsheet](https://developers.google.com/apps-script/guides/bound), if available.
2. A new spreadsheet with its name set to the script running Ob2ss. If one already exists, Ob2ss will use that.
Arguments:
| Name | Type | Description |
|---|
| spreadsheet | Spreadsheet | A Spreadsheet to open as an Ob2ss database. |
doSetDefaultTable(string tableName)
Sets a table as the default so you can call operations directly.
---
Setting a table as default means you can call other Ob2ss functions directly (e.g. `Ob2ss.addAppend()`) and they'll
operate on that default table. This serves two purposes:
1. You don't have to use `Ob2ss.getTableByName()` before every call, and
2. You can see the JSDoc documentation in the Apps Script IDE for when you _do_ want to use `Ob2ss.getTableByName()`.
_Example:_
```
Ob2ss.getTableByName('cars').addAppend(obj);
```
is the same as
```
Ob2ss.doSetDefaultTable('cars');
Ob2ss.addAppend(obj);
```
Arguments:
| Name | Type | Description |
|---|
| tableName | string | The name of the sheet to set as the default. |
getCount()
Gets the number of objects in the sheet.
---
Gets the total number of objects currently in the sheet.
Return Values:
| Type | Description |
|---|
number | The number of records in this sheet. |
removeLike(function selector)
Deletes the selected objects.
---
Removes rows (objects) found with the `selector` from the sheet.
_Example:_
```
Ob2ss.getTableByName('cars').removeLike((car){
car.make == 'saturn');
```
Arguments:
| Name | Type | Description |
|---|
| selector | function | A function callback that accepts one argument (a candidate object) and returns a boolean
indicating whether it should be selected. |
addPrepend(object[] objects)
Adds objects to the top (beginning) of the sheet.
---
Converts the provided array of objects into rows, and adds them to the top of the spreadsheet. This means
they'll appear at the beginning of the array of all objects stored.
Arguments:
| Name | Type | Description |
|---|
| objects | object[] | An array of objects to insert into the sheet. |
doDestroy(string tableName)
Deletes an entire sheet.
---
This will delete a sheet from the Spreadsheet. This is useful for testing or resetting a database. A `tableName` is
required and not inferred via any other calls to help avoid accidentally deleting a useful table.
Arguments:
| Name | Type | Description |
|---|
| tableName | string | The name of the sheet to delete. |
getColumns([string] headers)
Returns the requested columns for all objects.
---
This function will fetch and return the data columns for the specified headers, not including the header text
itself. This works identically to the built-in `getRange` feature in that it returns a 2 dimensional array of
values, first by rows and then by columns.
_Example:_
```
Ob2ss.getTableByName('cars').getColumns(['make', 'year']);
// Returns [['toyota', 2012],
// ['honda', 2014],
// ['honda', 2016]]
```
Arguments:
| Name | Type | Description |
|---|
| headers | [string] | An array of strings representing the headers to fetch. |
Return Values:
| Type | Description |
|---|
[object] | A 2-dimensional array representing the column values. |
getLike(function selector)
Returns objects filtered by the selector function.
---
_Example:_
```
Ob2ss.getTableByName('cars').getLike((car){
{
return car.model == 'camry' && car.year > 2016);
}
```
Arguments:
| Name | Type | Description |
|---|
| selector | function | A function callback that accepts one argument (a candidate object) and returns a boolean
indicating whether it should be selected. |
Return Values:
| Type | Description |
|---|
object[] | An array of objects the `selector` selected. |
getSequence(number skip, number count)
Returns a number of rows after skipping some.
---
This function will fetch and return any number of objects starting at an arbitrary position in the sheet. For
example, `Ob2ss.getRange(5, 3)` will return the 6th, 7th, and 8th objects from the sheet.
**Notes
1. The `skip` parameter refers to the data range of the sheet. If you have 3 header rows in your sheet and
you skip 3, Ob2ss will begin taking at row 7 (that's index 4).
2. If there are fewer rows available than were requested by the `count` parameter, those will be returned.
Arguments:
| Name | Type | Description |
|---|
| skip | number | The number of rows to skip. Remember that this is 1 based. |
| count | number | The number of rows to try to read and return. |
Return Values:
| Type | Description |
|---|
object[] | An array of objects representing the requested rows. |
getLast(number count)
Returns one or more last ("bottom") objects.
---
This function will fetch and return any number of objects from the bottom of the sheet. For example,
`Ob2ss.getLast(3)` will return the last 3 rows from the sheet as objects in the same order as they appear in the
sheet. For example, if you use `getLast(3)` on `[1,2,3,4,5,6]` you would get back `[4,5,6]`;
A count parameter is not required. If none is present, this will return the single last object.
Arguments:
| Name | Type | Description |
|---|
| count | number | [Optional] The number of top objects to return. If not supplied, the default is 1. |
Return Values:
| Type | Description |
|---|
object[] | An array of objects representing the requested rows. |
getColumnAsArray(string header)
Gets a single column as a flat array.
---
This function will return a single column as a flat array, and is faster than calling `getColumns()` on a single
column. Also, unlike `getColumns()`, this returns a 1-D array of values.
Arguments:
| Name | Type | Description |
|---|
| header | string | The header to fetch. |
Return Values:
| Type | Description |
|---|
any[] | A 1-D array of values of the column from top to bottom. |
getAll()
Returns all objects from the sheet.
---
Returns every object in the sheet as an array, in order.
Return Values:
| Type | Description |
|---|
object[] | An array of objects. |
doClear(string tableName)
Clears an entire sheet of its contents.
---
This will delete all the records in a sheet. This is useful for testing or resetting a database. A `tableName` is
required and not inferred via any other calls to help avoid accidentally clearing a useful table.
Arguments:
| Name | Type | Description |
|---|
| tableName | string | The name of the sheet to clear. |
addAt(object[] objects, number index)
Adds objects at the specified position in the sheet.
---
Converts the provided array of objects into rows, and adds them starting at the index provided. This means
they'll push other existing objects down on the sheet. Remember that the index is _not_ the same as the row number
of the sheet. The index represents the position in the data.
_Example:_
```
Ob2ss.getTableByName('cars').addAt(newCars, 5);
```
This code will insert the new cars after the first 4 cars in the table, at indices 5 through 9.
Arguments:
| Name | Type | Description |
|---|
| objects | object[] | An array of objects to insert into the sheet. |
| index | number | The position in the "data" to insert the objects. |