The group-by Reference Manual

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 4.0 beta 2 "William Riker" on Mon Aug 15 04:43:14 2022 GMT+0.

Table of Contents


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.

2 Systems

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


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

2.1 group-by

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

License

BSD

Version

0.1

Dependencies
  • iterate (system).
  • alexandria (system).
Source

group-by.asd.

Child Component

group-by.lisp (file).


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   [Contents][Index]

3.1.1 group-by/group-by.asd

Source

group-by.asd.

Parent Component

group-by (system).

ASDF Systems

group-by.

Packages

group-by.system.


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

3.1.2 group-by/group-by.lisp

Source

group-by.asd.

Parent Component

group-by (system).

Packages

group-by.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


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

4.1 group-by

Source

group-by.lisp.

Use List
  • common-lisp.
  • common-lisp-user.
  • iterate.
Public Interface
Internals

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

4.2 group-by.system

Source

group-by.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

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


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

5.1 Public Interface


5.1.1 Ordinary 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.

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.

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.

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.


5.1.2 Generic functions

Generic Function: add-item-to-grouping (item grouped-list)
Package

group-by.

Source

group-by.lisp.

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.

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.

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.

Methods
Method: items-in-group ((gl grouped-list) &rest key-values)
Generic Reader: key-value (object)
Generic Writer: (setf key-value) (object)
Package

group-by.

Methods
Reader Method: key-value ((grouped-list grouped-list))
Writer Method: (setf key-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.

Target Slot

key-value.

Generic Reader: keys (object)
Generic Writer: (setf keys) (object)
Package

group-by.

Methods
Reader Method: keys ((grouped-list grouped-list))
Writer Method: (setf keys) ((grouped-list grouped-list))

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

Source

group-by.lisp.

Target Slot

keys.

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.

Generic Reader: parent-grouping (object)
Generic Writer: (setf parent-grouping) (object)
Package

group-by.

Methods
Reader Method: parent-grouping ((grouped-list grouped-list))
Writer Method: (setf parent-grouping) ((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.

Target Slot

parent-grouping.

Generic Reader: tests (object)
Generic Writer: (setf tests) (object)
Package

group-by.

Methods
Reader Method: tests ((grouped-list grouped-list))
Writer Method: (setf tests) ((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.

Target Slot

tests.


5.1.3 Standalone methods

Method: initialize-instance :after ((o grouped-list) &key list &allow-other-keys)
Source

group-by.lisp.


5.1.4 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.

Direct methods
Direct slots
Slot: orig-list
Initargs

:orig-list

Readers

orig-list.

Writers

(setf orig-list).

Slot: grouping-implementation

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

Initform

:list

Initargs

:grouping-implementation

Readers

grouping-implementation.

Writers

(setf grouping-implementation).

Slot: keys

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

Initargs

:keys

Readers

keys.

Writers

(setf keys).

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.

Writers

(setf tests).

Slot: %child-groupings
Initargs

:%child-groupings

Readers

%child-groupings.

Writers

(setf %child-groupings).

Slot: %items
Initargs

:%items

Readers

%items.

Writers

(setf %items).

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.

Writers

(setf parent-grouping).

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.

Writers

(setf key-value).


5.2 Internals


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

5.2.1 Ordinary functions

Function: find-single-sub-category (gl key-value &key test)
Package

group-by.

Source

group-by.lisp.


5.2.2 Generic functions

Generic Reader: %child-groupings (object)
Package

group-by.

Methods
Reader Method: %child-groupings ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

%child-groupings.

Generic Writer: (setf %child-groupings) (object)
Package

group-by.

Methods
Writer Method: (setf %child-groupings) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

%child-groupings.

Generic Function: %grouping-items (grouped-list)
Package

group-by.

Source

group-by.lisp.

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

Returns the items in a given group

Generic Reader: %items (object)
Package

group-by.

Methods
Reader Method: %items ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

%items.

Generic Writer: (setf %items) (object)
Package

group-by.

Methods
Writer Method: (setf %items) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

%items.

Generic Reader: grouping-implementation (object)
Generic Writer: (setf grouping-implementation) (object)
Package

group-by.

Methods
Reader Method: grouping-implementation ((grouped-list grouped-list))
Writer Method: (setf grouping-implementation) ((grouped-list grouped-list))

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

Source

group-by.lisp.

Target Slot

grouping-implementation.

Generic Reader: orig-list (object)
Package

group-by.

Methods
Reader Method: orig-list ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

orig-list.

Generic Writer: (setf orig-list) (object)
Package

group-by.

Methods
Writer Method: (setf orig-list) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

orig-list.


Appendix A Indexes


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

A.1 Concepts


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: Private generic functions
%child-groupings: Private generic functions
%grouping-items: Private generic functions
%grouping-items: Private generic functions
%items: Private generic functions
%items: Private generic functions

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

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

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

F
find-single-sub-category: Private ordinary functions
Function, find-single-sub-category: Private ordinary functions
Function, group-by: Public ordinary functions
Function, group-by-repeated: Public ordinary functions
Function, grouped-list-speed-tester: Public ordinary functions
Function, make-grouped-list: Public ordinary functions

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

I
initialize-instance: Public standalone methods
items-in-group: Public generic functions
items-in-group: Public generic functions

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

M
make-child-grouped-list: Public generic functions
make-child-grouped-list: Public generic functions
make-grouped-list: Public ordinary functions
Method, %child-groupings: Private generic functions
Method, %grouping-items: Private generic functions
Method, %items: Private generic functions
Method, (setf %child-groupings): Private generic functions
Method, (setf %items): Private generic functions
Method, (setf grouping-implementation): Private generic functions
Method, (setf key-value): Public generic functions
Method, (setf keys): Public generic functions
Method, (setf orig-list): Private generic functions
Method, (setf parent-grouping): Public generic functions
Method, (setf tests): Public generic functions
Method, add-item-to-grouping: Public generic functions
Method, categorize-item: Public generic functions
Method, categorize-item: Public generic functions
Method, child-groupings: Public generic functions
Method, grouping-implementation: Private generic functions
Method, initialize-instance: Public standalone methods
Method, items-in-group: Public generic functions
Method, key-value: Public generic functions
Method, keys: Public generic functions
Method, make-child-grouped-list: Public generic functions
Method, orig-list: Private generic functions
Method, parent-grouping: Public generic functions
Method, tests: Public generic functions

O
orig-list: Private generic functions
orig-list: Private generic functions

P
parent-grouping: Public generic functions
parent-grouping: Public generic functions

T
tests: Public generic functions
tests: Public generic functions

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