The group-by Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The group-by Reference Manual

This is the group-by Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:53:41 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

= group-by = 
A Common Lisp library to help group data into trees (of various
formats) based on common/shared values

== API ==

=== group-by ===

groups the list into an alist using the key function and value function to group by key,
with a list of all values for that key.

''key'': is used to determine the key in the a-list 
''value'': is used to determine the value in the a-list
''key-fn'': is passed as the :key to assoc (essentially the key of your key)
''test'': is passed as the :test to assoc
eg: (group-by '((a 1 2) (a 3 4) (b 5 6)))
=> ((A (1 2) (3 4)) (B (5 6)))
eg: (group-by '((a 1 2) (a 3 4) (b 5 6)) :value #'identity)
=> ((A (A 1 2) (A 3 4)) (B (B 5 6)))
=== make-grouped-list, grouped-list === Given a list of input, produce a grouped-list CLOS object that contains the original list, configuration about the groupings and the result tree of grouped-list objects ''keys'': a list of keys to group by
''tests'': a list of tests to compare the keys with
''grouping-implmentation'': What data structure should be used to perform the grouping
'':list, :hash-table''
The implementation doesnt change the output, but it does change the performance characteristics of the grouped-object (see: grouped-list-speed-tester for help deciding which to use) ----
For the following docs consider the grouped list (as from examples)

grouped-list
  russ
    PROJ-A
      (list of timeclock records)
    PROJ-B
      (list of timeclock records)
    PROJ-C
      (list of timeclock records)
  bob
    PROJ-A
      (list of timeclock records)
    PROJ-B
      (list of timeclock records)
    PROJ-C
      (list of timeclock records)

==== key-value ==== Returns the key-value that this grouped-list represents nil for the root
the key we are grouping under otherwise
EG: the <gl russ> node returns the string "russ" ==== child-groupings ==== Returns the direct child grouped-lists of the current grouped-list If called on the root grouped list, will return a list of (<gl russ> <gl bob>)
If called on the "russ" grouped list, will return a list of (<gl PROJ-A> <gl PROJ-B> <gl PROJ-C>)
==== items-in-group ==== Returns all the items in a grouped list. ''key-values'':If specified, return only items that match When called on the root (items-in-group gl) of a grouped-list returns all of the items that list groups (leaf nodes of the tree). When called as (items-in-group gl "russ" :proj-a) returns the items under the key proj-A that are found under toplevel key "russ" === group-by-repeated === Sames as group-by, but groups on multiple keys and tests (into an alist tree) == Examples == * The [https://github.com/bobbysmith007/group-by/blob/master/examples/examples.lisp#L1 examples file] contains some examples increasing in complexity * [https://github.com/bobbysmith007/group-by/blob/master/tests/group-by.lisp#L83 The tests file also contains running examples] == Authors == * [http://www.acceleration.net/ Acceleration.net] [http://www.acceleration.net/programming/donate-to-acceleration-net/ Donate] ** [http://russ.unwashedmeme.com/blog Russ Tyndall] ** [http://the.unwashedmeme.com/blog Nathan Bird] ** [http://ryepup.unwashedmeme.com/blog Ryan Davis]
;; Copyright (c) 2011 Russ Tyndall , Acceleration.net http://www.acceleration.net
;; All rights reserved.
;;
;; Redistribution and use in source and binary forms, with or without
;; modification, are permitted provided that the following conditions are
;; met:
;;
;;  - Redistributions of source code must retain the above copyright
;;    notice, this list of conditions and the following disclaimer.
;;
;;  - Redistributions in binary form must reproduce the above copyright
;;    notice, this list of conditions and the following disclaimer in the
;;    documentation and/or other materials provided with the distribution.
;;
;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
;; A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 group-by

License

BSD

Description

A Common Lisp library to help group data into trees (of various formats) based on common/shared values

Version

0.1

Dependencies
Source

group-by.asd (file)

Component

group-by.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 group-by.asd

Location

group-by.asd

Systems

group-by (system)

Packages

group-by.system


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 group-by/group-by.lisp

Parent

group-by (system)

Location

group-by.lisp

Packages

group-by

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 group-by.system

Source

group-by.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 group-by

Source

group-by.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: group-by LIST &key KEY VALUE KEY-FN TEST

groups the list into an alist using the key function and value function to group by key, with a list of all values for that key.

key is used to determine the key in the a-list
value is used to determin the value in the a-list
key-fn is passed as the :key to assoc
test is passed as the :test to assoc

eg: (group-by ’((a 1 2) (a 3 4) (b 5 6)))
=> ((A (1 2) (3 4)) (B (5 6)))

Package

group-by

Source

group-by.lisp (file)

Function: group-by-repeated LIST &key KEYS TESTS

Returns an alist tree that represents the items in the list as categorized
by keys (compared with tests)
ex: ((a 3 sam) (c 4 bob) (a 3 ted))

keys: a list of key functions that describe the categorizations in order tests: how we are testing whether or not two keys are equal, defaults to #’equal

Package

group-by

Source

group-by.lisp (file)

Function: grouped-list-speed-tester &key LIST KEYS TESTS HASH-TESTS ITERATIONS ACTIONS

A function to help assess which implementation will work best in your given scenario actions : (lambda (gl) ...) -to help test whatever grouped list
operations you will need to do repeatedly

Package

group-by

Source

group-by.lisp (file)

Function: make-grouped-list INP &key TESTS KEYS GROUPING-IMPLEMENTATION

Given a list of input, produce a grouped-list CLOS object that contains
the original list, configuration about the groupings and the result tree
of grouped-list objects

”keys”: a list of keys to group by<br />
”tests”: a list of tests to compare the keys with<br />

”grouping-implmentation”: What data structure should be used to perform the grouping<br /> ”:alist, :tree , :hash-table”<br />
The implementation doesnt change the output, but it does change
the performance characteristics of the grouped-object (see:
grouped-list-speed-tester for help deciding which to use)

Package

group-by

Source

group-by.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: add-item-to-grouping ITEM GROUPED-LIST
Package

group-by

Source

group-by.lisp (file)

Methods
Method: add-item-to-grouping ITEM (GL grouped-list)

puts a new item in the grouping of the grouped list (but not in the original list)

Generic Function: categorize-item ITEM ROOT &key KEYS TESTS &allow-other-keys

Insert a new item into a grouped list

Package

group-by

Source

group-by.lisp (file)

Methods
Method: categorize-item ITEM (ROOT grouped-list) &key &allow-other-keys
Method: categorize-item ITEM (ROOT list) &key KEYS TESTS &allow-other-keys

Categorize a new item into an alist as produced by group-by-repeated This will create new category nodes if necessary

Generic Function: child-groupings GROUPED-LIST
Package

group-by

Source

group-by.lisp (file)

Methods
Method: child-groupings (GL grouped-list)
Generic Function: items-in-group GROUPED-LIST &rest KEYS

a list of key values that will produce a list of all the items in a given group

Package

group-by

Source

group-by.lisp (file)

Methods
Method: items-in-group (GL grouped-list) &rest KEY-VALUES
Generic Function: key-value OBJECT
Generic Function: (setf key-value) NEW-VALUE OBJECT
Package

group-by

Methods
Method: key-value (GROUPED-LIST grouped-list)
Method: (setf key-value) NEW-VALUE (GROUPED-LIST grouped-list)

If this is a subgrouping of another grouped-list, what is the key this grouped-list represents in the parent grouping (mostly for testing)

Source

group-by.lisp (file)

Generic Function: keys OBJECT
Generic Function: (setf keys) NEW-VALUE OBJECT
Package

group-by

Methods
Method: keys (GROUPED-LIST grouped-list)
Method: (setf keys) NEW-VALUE (GROUPED-LIST grouped-list)

A list of key functions we will use to group the list

Source

group-by.lisp (file)

Generic Function: make-child-grouped-list GL KEY-VALUE GROUPED-LIST
Package

group-by

Methods
Method: make-child-grouped-list (GL grouped-list) KEY-VALUE GROUPED-LIST
Source

group-by.lisp (file)

Generic Function: parent-grouping OBJECT
Generic Function: (setf parent-grouping) NEW-VALUE OBJECT
Package

group-by

Methods
Method: parent-grouping (GROUPED-LIST grouped-list)
Method: (setf parent-grouping) NEW-VALUE (GROUPED-LIST grouped-list)

If this is a subgrouping of another grouped-list, what is the parent grouping we are apart of (mostly for testing)

Source

group-by.lisp (file)

Generic Function: tests OBJECT
Generic Function: (setf tests) NEW-VALUE OBJECT
Package

group-by

Methods
Method: tests (GROUPED-LIST grouped-list)
Method: (setf tests) NEW-VALUE (GROUPED-LIST grouped-list)

A list of test functions we will use to test key equality
tree: defaults to #’equal
hash-table: this be a single hash-equality symbol (defaults to ’equal)

Source

group-by.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Classes

Class: grouped-list ()

This class represents a list that we have grouped by multiple key values ala one of the group-by-repeatedly functions

Package

group-by

Source

group-by.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: orig-list
Initargs

:orig-list

Readers

orig-list (generic function)

Writers

(setf orig-list) (generic function)

Slot: grouping-implementation

What data structure should be used to perform the grouping :list, :hash-table

Initargs

:grouping-implementation

Initform

:list

Readers

grouping-implementation (generic function)

Writers

(setf grouping-implementation) (generic function)

Slot: keys

A list of key functions we will use to group the list

Initargs

:keys

Readers

keys (generic function)

Writers

(setf keys) (generic function)

Slot: tests

A list of test functions we will use to test key equality
tree: defaults to #’equal
hash-table: this be a single hash-equality symbol (defaults to ’equal)

Initargs

:tests

Readers

tests (generic function)

Writers

(setf tests) (generic function)

Slot: %child-groupings
Initargs

:%child-groupings

Readers

%child-groupings (generic function)

Writers

(setf %child-groupings) (generic function)

Slot: %items
Initargs

:%items

Readers

%items (generic function)

Writers

(setf %items) (generic function)

Slot: parent-grouping

If this is a subgrouping of another grouped-list, what is the parent grouping we are apart of (mostly for testing)

Initargs

:parent

Readers

parent-grouping (generic function)

Writers

(setf parent-grouping) (generic function)

Slot: key-value

If this is a subgrouping of another grouped-list, what is the key this grouped-list represents in the parent grouping (mostly for testing)

Initargs

:key-value

Readers

key-value (generic function)

Writers

(setf key-value) (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: find-single-sub-category GL KEY-VALUE &key TEST
Package

group-by

Source

group-by.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: %child-groupings OBJECT
Generic Function: (setf %child-groupings) NEW-VALUE OBJECT
Package

group-by

Methods
Method: %child-groupings (GROUPED-LIST grouped-list)

automatically generated reader method

Source

group-by.lisp (file)

Method: (setf %child-groupings) NEW-VALUE (GROUPED-LIST grouped-list)

automatically generated writer method

Source

group-by.lisp (file)

Generic Function: %grouping-items GROUPED-LIST
Package

group-by

Source

group-by.lisp (file)

Methods
Method: %grouping-items (GL grouped-list)

Returns the items in a given group

Generic Function: %items OBJECT
Generic Function: (setf %items) NEW-VALUE OBJECT
Package

group-by

Methods
Method: %items (GROUPED-LIST grouped-list)

automatically generated reader method

Source

group-by.lisp (file)

Method: (setf %items) NEW-VALUE (GROUPED-LIST grouped-list)

automatically generated writer method

Source

group-by.lisp (file)

Generic Function: grouping-implementation OBJECT
Generic Function: (setf grouping-implementation) NEW-VALUE OBJECT
Package

group-by

Methods
Method: grouping-implementation (GROUPED-LIST grouped-list)
Method: (setf grouping-implementation) NEW-VALUE (GROUPED-LIST grouped-list)

What data structure should be used to perform the grouping :list, :hash-table

Source

group-by.lisp (file)

Generic Function: orig-list OBJECT
Generic Function: (setf orig-list) NEW-VALUE OBJECT
Package

group-by

Methods
Method: orig-list (GROUPED-LIST grouped-list)

automatically generated reader method

Source

group-by.lisp (file)

Method: (setf orig-list) NEW-VALUE (GROUPED-LIST grouped-list)

automatically generated writer method

Source

group-by.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   G   L  
Index Entry  Section

F
File, Lisp, group-by.asd: The group-by<dot>asd file
File, Lisp, group-by/group-by.lisp: The group-by/group-by<dot>lisp file

G
group-by.asd: The group-by<dot>asd file
group-by/group-by.lisp: The group-by/group-by<dot>lisp file

L
Lisp File, group-by.asd: The group-by<dot>asd file
Lisp File, group-by/group-by.lisp: The group-by/group-by<dot>lisp file

Jump to:   F   G   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   C   F   G   I   K   M   O   P   T  
Index Entry  Section

%
%child-groupings: Internal generic functions
%child-groupings: Internal generic functions
%grouping-items: Internal generic functions
%grouping-items: Internal generic functions
%items: Internal generic functions
%items: Internal generic functions

(
(setf %child-groupings): Internal generic functions
(setf %child-groupings): Internal generic functions
(setf %items): Internal generic functions
(setf %items): Internal generic functions
(setf grouping-implementation): Internal generic functions
(setf grouping-implementation): Internal generic functions
(setf key-value): Exported generic functions
(setf key-value): Exported generic functions
(setf keys): Exported generic functions
(setf keys): Exported generic functions
(setf orig-list): Internal generic functions
(setf orig-list): Internal generic functions
(setf parent-grouping): Exported generic functions
(setf parent-grouping): Exported generic functions
(setf tests): Exported generic functions
(setf tests): Exported generic functions

A
add-item-to-grouping: Exported generic functions
add-item-to-grouping: Exported generic functions

C
categorize-item: Exported generic functions
categorize-item: Exported generic functions
categorize-item: Exported generic functions
child-groupings: Exported generic functions
child-groupings: Exported generic functions

F
find-single-sub-category: Internal functions
Function, find-single-sub-category: Internal functions
Function, group-by: Exported functions
Function, group-by-repeated: Exported functions
Function, grouped-list-speed-tester: Exported functions
Function, make-grouped-list: Exported functions

G
Generic Function, %child-groupings: Internal generic functions
Generic Function, %grouping-items: Internal generic functions
Generic Function, %items: Internal generic functions
Generic Function, (setf %child-groupings): Internal generic functions
Generic Function, (setf %items): Internal generic functions
Generic Function, (setf grouping-implementation): Internal generic functions
Generic Function, (setf key-value): Exported generic functions
Generic Function, (setf keys): Exported generic functions
Generic Function, (setf orig-list): Internal generic functions
Generic Function, (setf parent-grouping): Exported generic functions
Generic Function, (setf tests): Exported generic functions
Generic Function, add-item-to-grouping: Exported generic functions
Generic Function, categorize-item: Exported generic functions
Generic Function, child-groupings: Exported generic functions
Generic Function, grouping-implementation: Internal generic functions
Generic Function, items-in-group: Exported generic functions
Generic Function, key-value: Exported generic functions
Generic Function, keys: Exported generic functions
Generic Function, make-child-grouped-list: Exported generic functions
Generic Function, orig-list: Internal generic functions
Generic Function, parent-grouping: Exported generic functions
Generic Function, tests: Exported generic functions
group-by: Exported functions
group-by-repeated: Exported functions
grouped-list-speed-tester: Exported functions
grouping-implementation: Internal generic functions
grouping-implementation: Internal generic functions

I
items-in-group: Exported generic functions
items-in-group: Exported generic functions

K
key-value: Exported generic functions
key-value: Exported generic functions
keys: Exported generic functions
keys: Exported generic functions

M
make-child-grouped-list: Exported generic functions
make-child-grouped-list: Exported generic functions
make-grouped-list: Exported functions
Method, %child-groupings: Internal generic functions
Method, %grouping-items: Internal generic functions
Method, %items: Internal generic functions
Method, (setf %child-groupings): Internal generic functions
Method, (setf %items): Internal generic functions
Method, (setf grouping-implementation): Internal generic functions
Method, (setf key-value): Exported generic functions
Method, (setf keys): Exported generic functions
Method, (setf orig-list): Internal generic functions
Method, (setf parent-grouping): Exported generic functions
Method, (setf tests): Exported generic functions
Method, add-item-to-grouping: Exported generic functions
Method, categorize-item: Exported generic functions
Method, categorize-item: Exported generic functions
Method, child-groupings: Exported generic functions
Method, grouping-implementation: Internal generic functions
Method, items-in-group: Exported generic functions
Method, key-value: Exported generic functions
Method, keys: Exported generic functions
Method, make-child-grouped-list: Exported generic functions
Method, orig-list: Internal generic functions
Method, parent-grouping: Exported generic functions
Method, tests: Exported generic functions

O
orig-list: Internal generic functions
orig-list: Internal generic functions

P
parent-grouping: Exported generic functions
parent-grouping: Exported generic functions

T
tests: Exported generic functions
tests: Exported generic functions

Jump to:   %   (  
A   C   F   G   I   K   M   O   P   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %  
G   K   O   P   S   T  
Index Entry  Section

%
%child-groupings: Exported classes
%items: Exported classes

G
grouping-implementation: Exported classes

K
key-value: Exported classes
keys: Exported classes

O
orig-list: Exported classes

P
parent-grouping: Exported classes

S
Slot, %child-groupings: Exported classes
Slot, %items: Exported classes
Slot, grouping-implementation: Exported classes
Slot, key-value: Exported classes
Slot, keys: Exported classes
Slot, orig-list: Exported classes
Slot, parent-grouping: Exported classes
Slot, tests: Exported classes

T
tests: Exported classes

Jump to:   %  
G   K   O   P   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   G   P   S  
Index Entry  Section

C
Class, grouped-list: Exported classes

G
group-by: The group-by system
group-by: The group-by package
group-by.system: The group-by<dot>system package
grouped-list: Exported classes

P
Package, group-by: The group-by package
Package, group-by.system: The group-by<dot>system package

S
System, group-by: The group-by system

Jump to:   C   G   P   S