Mercurial > p > roundup > code

annotate doc/spec.html @ 4774:3adff0fb0207

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed issue2550595: Allow migrating from roundup 0.x to 1.4 All changes were required to make an upgrade from 0.6 to 1.4, The changes affecting "retired" were required for an upgrade from 0.8 to 1.4.
author Thomas Arendsen Hein <thomas@intevation.de>
date Fri, 22 Mar 2013 15:53:27 +0100
parents b9c1226cb600
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 <html>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 <head>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 <title>Software Carpentry Track: Roundup</title>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4 </head>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 <body bgcolor=white>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 <table width="100%">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 <td align="left">
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 71
diff changeset
11 <a href="http://www.software-carpentry.com"><img
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 71
diff changeset
12 src="images/logo-software-carpentry-standard.png" alt="[Software Carpentry logo]" border="0"></a>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 <td align="right">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 <table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 <tr><td>
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 71
diff changeset
18 <a href="http://www.acl.lanl.gov"><img src="images//logo-acl-medium.png" alt="[ACL Logo]" border="0"></a>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 </td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 <tr><td><hr></td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 <tr><td>
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 71
diff changeset
22 <a href="http://www.codesourcery.com"><img
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 71
diff changeset
23 src="images/logo-codesourcery-medium.png" alt="[CodeSourcery Logo]" border="0"></a>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 </td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 <hr><p>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 <h1 align=center>Roundup</h1>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 <h4 align=center><a href="http://www.lfw.org/ping/">Ka-Ping Yee</a><br>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 <a href="mailto:ping@lfw.org">ping@lfw.org</a></h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 <h3 align=center>Implementation Guide</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 <h2>Contents</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 <li>Introduction
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 <li>The Layer Cake
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 <li>Hyperdatabase
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 <li>Dates and Date Arithmetic
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
47 <li>Items and Classes
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 <li>Identifiers and Designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49 <li>Property Names and Types
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 <li>Application Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 <li>Roundup Database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 <li>Reserved Classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57 <li>Users
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58 <li>Messages
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59 <li>Files
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 <li>Item Classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 <li>Default Schema
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 <li>Detector Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 <li>Detector Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 <li>Command Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 <li>Usage Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 <li>E-mail User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 <li>Message Processing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 <li>Nosy Lists
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 <li>Setting Properties
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 <li>Workflow Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 <li>Web User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 <li>Views and View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 <li>Displaying Properties
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 <li>Index Views
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88 <li>Index View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 <li>Filter Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 <li>Index Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 <li>Sorting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 <li>Item Views
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 <li>Item View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 <li>Editor Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 <li>Spool Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 <li>Deployment Scenarios
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 <li>Acknowledgements
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 <h2>1. Introduction</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 <p>This document presents a description of the components
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 of the Roundup system and specifies their interfaces and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 behaviour in sufficient detail to guide an implementation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 For the philosophy and rationale behind the Roundup design,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 see the first-round Software Carpentry submission for Roundup.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 This document fleshes out that design as well as specifying
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 interfaces so that the components can be developed separately.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116 <h2>2. The Layer Cake</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 <p>Lots of software design documents come with a picture of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 a cake. Everybody seems to like them. I also like cakes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 (i think they are tasty). So i, too, shall include
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 a picture of a cake here.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 <p align=center><table cellspacing=0 cellpadding=10 border=0 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 <td bgcolor="#e8e8e8" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 E-mail Client
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 <td bgcolor="#e0e0e0" align="center">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 Web Browser
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 <td bgcolor="#e8e8e8" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 Detector Scripts
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140 <td bgcolor="#e0e0e0" align="center">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 Shell
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 <td bgcolor="#d0d0f0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 E-mail User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 <td bgcolor="#f0d0d0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 Web User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 <td bgcolor="#d0f0d0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 Detector Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 <td bgcolor="#f0d0f0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 Command Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 <td bgcolor="#f0f0d0" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 Roundup Database Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 <td bgcolor="#d0f0f0" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 Hyperdatabase Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 <td bgcolor="#e8e8e8" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 Storage Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186 <p>The colourful parts of the cake are part of our system;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 the faint grey parts of the cake are external components.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 <p>I will now proceed to forgo all table manners and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 eat from the bottom of the cake to the top. You may want
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191 to stand back a bit so you don't get covered in crumbs.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194 <h2>3. Hyperdatabase</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 <p>The lowest-level component to be implemented is the hyperdatabase.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 The hyperdatabase is intended to be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 a flexible data store that can hold configurable data in
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
199 records which we call <em>items</em>.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 <p>The hyperdatabase is implemented on top of the storage layer,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 an external module for storing its data. The storage layer could
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203 be a third-party RDBMS; for a "batteries-included" distribution,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 implementing the hyperdatabase on the standard <tt>bsddb</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 module is suggested.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 <h3>3.1. Dates and Date Arithmetic</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 <p>Before we get into the hyperdatabase itself, we need a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 way of handling dates. The hyperdatabase module provides
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 Timestamp objects for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 representing date-and-time stamps and Interval objects for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213 representing date-and-time intervals.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 <p>As strings, date-and-time stamps are specified with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 the date in international standard format
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 (<em>yyyy</em>-<em>mm</em>-<em>dd</em>)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 joined to the time (<em>hh</em>:<em>mm</em>:<em>ss</em>)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 by a period ("."). Dates in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 this form can be easily compared and are fairly readable
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 when printed. An example of a valid stamp is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222 "<strong>2000-06-24.13:03:59</strong>".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 We'll call this the "full date format". When Timestamp objects are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 printed as strings, they appear in the full date format with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 the time always given in GMT. The full date format is always
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 exactly 19 characters long.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 <p>For user input, some partial forms are also permitted:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 the whole time or just the seconds may be omitted; and the whole date
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230 may be omitted or just the year may be omitted. If the time is given,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 the time is interpreted in the user's local time zone.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 The <tt>Date</tt> constructor takes care of these conversions.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233 In the following examples, suppose that <em>yyyy</em> is the current year,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 <em>mm</em> is the current month, and <em>dd</em> is the current
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235 day of the month; and suppose that the user is on Eastern Standard Time.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 <li>"<strong>2000-04-17</strong>" means &lt;Date 2000-04-17.00:00:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 <li>"<strong>01-25</strong>" means &lt;Date <em>yyyy</em>-01-25.00:00:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240 <li>"<strong>2000-04-17.03:45</strong>" means &lt;Date 2000-04-17.08:45:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 <li>"<strong>08-13.22:13</strong>" means &lt;Date <em>yyyy</em>-08-14.03:13:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242 <li>"<strong>11-07.09:32:43</strong>" means &lt;Date <em>yyyy</em>-11-07.14:32:43&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243 <li>"<strong>14:25</strong>" means
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 &lt;Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.19:25:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245 <li>"<strong>8:47:11</strong>" means
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 &lt;Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.13:47:11&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 <li>the special date "<strong>.</strong>" means "right now"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 <p>Date intervals are specified using the suffixes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 "y", "m", and "d". The suffix "w" (for "week") means 7 days.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252 Time intervals are specified in hh:mm:ss format (the seconds
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 may be omitted, but the hours and minutes may not).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 <li>"<strong>3y</strong>" means three years
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 <li>"<strong>2y 1m</strong>" means two years and one month
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 <li>"<strong>1m 25d</strong>" means one month and 25 days
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 <li>"<strong>2w 3d</strong>" means two weeks and three days
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260 <li>"<strong>1d 2:50</strong>" means one day, two hours, and 50 minutes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 <li>"<strong>14:00</strong>" means 14 hours
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 <li>"<strong>0:04:33</strong>" means four minutes and 33 seconds
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 <p>The Date class should understand simple date expressions of the form
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 <em>stamp</em> + <em>interval</em> and <em>stamp</em> - <em>interval</em>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 When adding or subtracting intervals involving months or years, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 components are handled separately. For example, when evaluating
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 "<strong>2000-06-25 + 1m 10d</strong>", we first add one month to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270 get <strong>2000-07-25</strong>, then add 10 days to get
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 <strong>2000-08-04</strong> (rather than trying to decide whether
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272 <strong>1m 10d</strong> means 38 or 40 or 41 days).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274 <p>Here is an outline of the Date and Interval classes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276 <blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
277 <pre><small>class <strong>Date</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278 def <strong>__init__</strong>(self, spec, offset):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279 """Construct a date given a specification and a time zone offset.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 'spec' is a full date or a partial form, with an optional
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 added or subtracted interval. 'offset' is the local time
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283 zone offset from GMT in hours.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286 def <strong>__add__</strong>(self, interval):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 """Add an interval to this date to produce another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
288
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289 def <strong>__sub__</strong>(self, interval):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 """Subtract an interval from this date to produce another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292 def <strong>__cmp__</strong>(self, other):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293 """Compare this date to another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295 def <strong>__str__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
296 """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298 def <strong>local</strong>(self, offset):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
299 """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301 class <strong>Interval</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
302 def <strong>__init__</strong>(self, spec):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303 """Construct an interval given a specification."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305 def <strong>__cmp__</strong>(self, other):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 """Compare this interval to another interval."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308 def <strong>__str__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 """Return this interval as a string."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310 </small></pre>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 </blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 <p>Here are some examples of how these classes would behave in practice.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314 For the following examples, assume that we are on Eastern Standard
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 Time and the current local time is 19:34:02 on 25 June 2000.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
318 >&gt;&gt;&gt; <span class="input">Date(".")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319 <span class="output">&lt;Date 2000-06-26.00:34:02&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320 &gt;&gt;&gt; <span class="input">_.local(-5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 <span class="output">"2000-06-25.19:34:02"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 &gt;&gt;&gt; <span class="input">Date(". + 2d")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323 <span class="output">&lt;Date 2000-06-28.00:34:02&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 &gt;&gt;&gt; <span class="input">Date("1997-04-17", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325 <span class="output">&lt;Date 1997-04-17.00:00:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 &gt;&gt;&gt; <span class="input">Date("01-25", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327 <span class="output">&lt;Date 2000-01-25.00:00:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328 &gt;&gt;&gt; <span class="input">Date("08-13.22:13", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 <span class="output">&lt;Date 2000-08-14.03:13:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 &gt;&gt;&gt; <span class="input">Date("14:25", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331 <span class="output">&lt;Date 2000-06-25.19:25:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 &gt;&gt;&gt; <span class="input">Interval(" 3w 1 d 2:00")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333 <span class="output">&lt;Interval 22d 2:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
334 &gt;&gt;&gt; <span class="input">Date(". + 2d") - Interval("3w")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
335 <span class="output">&lt;Date 2000-06-07.00:34:02&gt;</span
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
336 ></small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
337
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
338 <h3>3.2. Items and Classes</h3>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
340 <p>Items contain data in <em>properties</em>. To Python, these
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
341 properties are presented as the key-value pairs of a dictionary.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
342 Each item belongs to a <em>class</em> which defines the names
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
343 and types of its properties. The database permits the creation
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
344 and modification of classes as well as items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
345
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
346 <h3>3.3. Identifiers and Designators</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
347
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
348 <p>Each item has a numeric identifier which is unique among
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
349 items in its class. The items are numbered sequentially
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350 within each class in order of creation, starting from 1.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
351 The <em>designator</em>
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
352 for an item is a way to identify an item in the database, and
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
353 consists of the name of the item's class concatenated with
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
354 the item's numeric identifier.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356 <p>For example, if "spam" and "eggs" are classes, the first
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
357 item created in class "spam" has id 1 and designator "spam1".
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
358 The first item created in class "eggs" also has id 1 but has
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
359 the distinct designator "eggs1". Item designators are
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
360 conventionally enclosed in square brackets when mentioned
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361 in plain text. This permits a casual mention of, say,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362 "[patch37]" in an e-mail message to be turned into an active
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363 hyperlink.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 <h3>3.4. Property Names and Types</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 <p>Property names must begin with a letter.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 <p>A property may be one of five <em>basic types</em>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372 <li><em>String</em> properties are for storing arbitrary-length
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373 strings.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375 <li><em>Date</em> properties store date-and-time stamps.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376 Their values are Timestamp objects.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
378 <li>A <em>Link</em> property refers to a single other item
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379 selected from a specified class. The class is part of the property;
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
380 the value is an integer, the id of the chosen item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
382 <li>A <em>Multilink</em> property refers to possibly many items
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383 in a specified class. The value is a list of integers.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 <p><tt>None</tt> is also a permitted value for any of these property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387 types. An attempt to store <tt>None</tt> into a String property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388 stores the empty string; an attempt to store <tt>None</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389 into a Multilink property stores an empty list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391 <h3>3.5. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 <p>The hyperdb module provides property objects to designate
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394 the different kinds of properties. These objects are used when
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395 specifying what properties belong in classes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 >class <strong>String</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399 def <strong>__init__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400 """An object designating a String property."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402 class <strong>Date</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403 def <strong>__init__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 """An object designating a Date property."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406 class <strong>Link</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 def <strong>__init__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408 """An object designating a Link property that links to
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
409 items in a specified class."""
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 class <strong>Multilink</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 def <strong>__init__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413 """An object designating a Multilink property that links
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
414 to items in a specified class."""
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 <p>Here is the interface provided by the hyperdatabase.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420 >class <strong>Database</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421 """A database for storing records containing flexible data types."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423 def <strong>__init__</strong>(self, storagelocator, journaltag):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
424 """Open a hyperdatabase given a specifier to some storage.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 The meaning of 'storagelocator' depends on the particular
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427 implementation of the hyperdatabase. It could be a file name,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428 a directory path, a socket descriptor for a connection to a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
429 database over the network, etc.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
430
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431 The 'journaltag' is a token that will be attached to the journal
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
432 entries for any edits done on the database. If 'journaltag' is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433 None, the database is opened in read-only mode: the Class.create(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
434 Class.set(), and Class.retire() methods are disabled.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
436
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437 def <strong>__getattr__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438 """A convenient way of calling self.getclass(classname)."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
439
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
440 def <strong>getclasses</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
441 """Return a list of the names of all existing classes."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
442
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
443 def <strong>getclass</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444 """Get the Class object representing a particular class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446 If 'classname' is not a valid class name, a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449 class <strong>Class</strong>:
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
450 """The handle to a particular class of items in a hyperdatabase."""
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452 def <strong>__init__</strong>(self, db, classname, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 """Create a new class with a given name and property specification.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455 'classname' must not collide with the name of an existing class,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 or a ValueError is raised. The keyword arguments in 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457 must map names to property objects, or a TypeError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
460 # Editing items:
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 def <strong>create</strong>(self, **propvalues):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
463 """Create a new item of this class and return its id.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 The keyword arguments in 'propvalues' map property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466 The values of arguments must be acceptable for the types of their
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 corresponding properties or a TypeError is raised. If this class
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 has a key property, it must be present and its value must not
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469 collide with other key strings or a ValueError is raised. Any other
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 properties on this class that are missing from the 'propvalues'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 dictionary are set to None. If an id in a link or multilink
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
472 property does not refer to a valid item, an IndexError is raised.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
475 def <strong>get</strong>(self, itemid, propname):
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
476 """Get the value of a property on an existing item of this class.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
478 'itemid' must be the id of an existing item of this class or an
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
479 IndexError is raised. 'propname' must be the name of a property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
480 of this class or a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
481 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
483 def <strong>set</strong>(self, itemid, **propvalues):
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
484 """Modify a property on an existing item of this class.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
486 'itemid' must be the id of an existing item of this class or an
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 IndexError is raised. Each key in 'propvalues' must be the name
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 of a property of this class or a KeyError is raised. All values
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489 in 'propvalues' must be acceptable types for their corresponding
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 properties or a TypeError is raised. If the value of the key
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 property is set, it must not collide with other key strings or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492 ValueError is raised. If the value of a Link or Multilink
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
493 property contains an invalid item id, a ValueError is raised.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
496 def <strong>retire</strong>(self, itemid):
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
497 """Retire an item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
499 The properties on the item remain available from the get() method,
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
500 and the item's id is never reused. Retired items are not returned
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
501 by the find(), list(), or lookup() methods, and other items may
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502 reuse the values of their key properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
505 def <strong>history</strong>(self, itemid):
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
506 """Retrieve the journal of edits on a particular item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
508 'itemid' must be the id of an existing item of this class or an
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 IndexError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 The returned list contains tuples of the form
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513 (date, tag, action, params)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 'date' is a Timestamp object specifying the time of the change and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516 'tag' is the journaltag specified when the database was opened.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
517 'action' may be:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
519 'create' or 'set' -- 'params' is a dictionary of property values
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
520 'link' or 'unlink' -- 'params' is (classname, itemid, propname)
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521 'retire' -- 'params' is None
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
524 # Locating items:
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
525
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
526 def <strong>setkey</strong>(self, propname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
527 """Select a String property of this class to be the key property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
528
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 'propname' must be the name of a String property of this class or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530 None, or a TypeError is raised. The values of the key property on
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
531 all existing items must be unique or a ValueError is raised.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
532 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
533
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
534 def <strong>getkey</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535 """Return the name of the key property for this class or None."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537 def <strong>lookup</strong>(self, keyvalue):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
538 """Locate a particular item by its key property and return its id.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 If this class has no key property, a TypeError is raised. If the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 'keyvalue' matches one of the values for the key property among
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
542 the items in this class, the matching item's id is returned;
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543 otherwise a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
546 def <strong>find</strong>(self, propname, itemid):
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
547 """Get the ids of items in this class which link to a given item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 'propname' must be the name of a property in this class, or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550 KeyError is raised. That property must be a Link or Multilink
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
551 property, or a TypeError is raised. 'itemid' must be the id of
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
552 an existing item in the class linked to by the given property,
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 or an IndexError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556 def <strong>list</strong>(self):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
557 """Return a list of the ids of the active items in this class."""
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559 def <strong>count</strong>(self):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
560 """Get the number of items in this class.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
562 If the returned integer is 'numitems', the ids of all the items
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
563 in this class run from 1 to numitems, and numitems+1 will be the
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
564 id of the next item to be created in this class.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567 # Manipulating properties:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569 def <strong>getprops</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 """Return a dictionary mapping property names to property objects."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572 def <strong>addprop</strong>(self, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 """Add properties to this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 The keyword arguments in 'properties' must map names to property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576 objects, or a TypeError is raised. None of the keys in 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 may collide with the names of existing properties, or a ValueError
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 is raised before any properties have been added.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 """</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 <h3>3.6. Application Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 <p>Here is an example of how the hyperdatabase module would work in practice.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 >&gt;&gt;&gt; <span class="input">import hyperdb</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 &gt;&gt;&gt; <span class="input">db = hyperdb.Database("foo.db", "ping")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 &gt;&gt;&gt; <span class="input">db</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 <span class="output">&lt;hyperdb.Database "foo.db" opened by "ping"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "status", name=hyperdb.String())</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 <span class="output">&lt;hyperdb.Class "status"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 &gt;&gt;&gt; <span class="input">_.setkey("name")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 &gt;&gt;&gt; <span class="input">db.status.create(name="unread")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 <span class="output">1</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595 &gt;&gt;&gt; <span class="input">db.status.create(name="in-progress")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 &gt;&gt;&gt; <span class="input">db.status.create(name="testing")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 <span class="output">3</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 &gt;&gt;&gt; <span class="input">db.status.create(name="resolved")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 &gt;&gt;&gt; <span class="input">db.status.count()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
602 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603 &gt;&gt;&gt; <span class="input">db.status.list()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 <span class="output">[1, 2, 3, 4]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 &gt;&gt;&gt; <span class="input">db.status.lookup("in-progress")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 &gt;&gt;&gt; <span class="input">db.status.retire(3)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 &gt;&gt;&gt; <span class="input">db.status.list()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 <span class="output">[1, 2, 4]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 <span class="output">&lt;hyperdb.Class "issue"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612 &gt;&gt;&gt; <span class="input">db.issue.create(title="spam", status=1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613 <span class="output">1</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 &gt;&gt;&gt; <span class="input">db.issue.create(title="eggs", status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616 &gt;&gt;&gt; <span class="input">db.issue.create(title="ham", status=4)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 <span class="output">3</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
618 &gt;&gt;&gt; <span class="input">db.issue.create(title="arguments", status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
619 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
620 &gt;&gt;&gt; <span class="input">db.issue.create(title="abuse", status=1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621 <span class="output">5</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
622 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623 <span class="output">&lt;hyperdb.Class "user"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624 &gt;&gt;&gt; <span class="input">db.issue.addprop(fixer=hyperdb.Link("user"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625 &gt;&gt;&gt; <span class="input">db.issue.getprops()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
626 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
627 >{"title": &lt;hyperdb.String&gt;, "status": &lt;hyperdb.Link to "status"&gt;,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628 "user": &lt;hyperdb.Link to "user"&gt;}</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
629 &gt;&gt;&gt; <span class="input">db.issue.set(5, status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
630 &gt;&gt;&gt; <span class="input">db.issue.get(5, "status")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
631 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
632 &gt;&gt;&gt; <span class="input">db.status.get(2, "name")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
633 <span class="output">"in-progress"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634 &gt;&gt;&gt; <span class="input">db.issue.get(5, "title")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
635 <span class="output">"abuse"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
636 &gt;&gt;&gt; <span class="input">db.issue.find("status", db.status.lookup("in-progress"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637 <span class="output">[2, 4, 5]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638 &gt;&gt;&gt; <span class="input">db.issue.history(5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
639 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
640 >[(&lt;Date 2000-06-28.19:09:43&gt;, "ping", "create", {"title": "abuse", "status": 1}),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
641 (&lt;Date 2000-06-28.19:11:04&gt;, "ping", "set", {"status": 2})]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
642 &gt;&gt;&gt; <span class="input">db.status.history(1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
643 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
644 >[(&lt;Date 2000-06-28.19:09:43&gt;, "ping", "link", ("issue", 5, "status")),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
645 (&lt;Date 2000-06-28.19:11:04&gt;, "ping", "unlink", ("issue", 5, "status"))]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646 &gt;&gt;&gt; <span class="input">db.status.history(2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
648 >[(&lt;Date 2000-06-28.19:11:04&gt;, "ping", "link", ("issue", 5, "status"))]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
649 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651 <p>For the purposes of journalling, when a Multilink property is
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
652 set to a new list of items, the hyperdatabase compares the old
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
653 list to the new list.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
654 The journal records "unlink" events for all the items that appear
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
655 in the old list but not the new list,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
656 and "link" events for
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
657 all the items that appear in the new list but not in the old list.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
658
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
659 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
660 <h2>4. Roundup Database</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
661
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
662 <p>The Roundup database layer is implemented on top of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
663 hyperdatabase and mediates calls to the database.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
664 Some of the classes in the Roundup database are considered
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
665 <em>item classes</em>.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
666 The Roundup database layer adds detectors and user items,
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
667 and on items it provides mail spools, nosy lists, and superseders.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
668
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
669 <h3>4.1. Reserved Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
670
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
671 <p>Internal to this layer we reserve three special classes
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
672 of items that are not items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
673
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
674 <h4>4.1.1. Users</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
675
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
676 <p>Users are stored in the hyperdatabase as items of
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
677 class "user". The "user" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680 >hyperdb.Class(db, "user", username=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681 password=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
682 address=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
683 db.user.setkey("username")</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
684
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
685 <h4>4.1.2. Messages</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
686
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
687 <p>E-mail messages are represented by hyperdatabase items of class "msg".
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
688 The actual text content of the messages is stored in separate files.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
689 (There's no advantage to be gained by stuffing them into the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
690 hyperdatabase, and if messages are stored in ordinary text files,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
691 they can be grepped from the command line.) The text of a message is
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
692 saved in a file named after the message item designator (e.g. "msg23")
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
693 for the sake of the command interface (see below). Attachments are
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
694 stored separately and associated with "file" items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
695 The "msg" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
696
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
697 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
698 >hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
699 recipients=hyperdb.Multilink("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
700 date=hyperdb.Date(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
701 summary=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
702 files=hyperdb.Multilink("file"))</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
703 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
704
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
705 <p>The "author" property indicates the author of the message
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
706 (a "user" item must exist in the hyperdatabase for any messages
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
707 that are stored in the system).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
708 The "summary" property contains a summary of the message for display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
709 in a message index.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
710
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
711 <h4>4.1.3. Files</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
712
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
713 <p>Submitted files are represented by hyperdatabase
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
714 items of class "file". Like e-mail messages, the file content
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
715 is stored in files outside the database,
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
716 named after the file item designator (e.g. "file17").
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
717 The "file" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
718
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
719 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
720 >hyperdb.Class(db, "file", user=hyperdb.Link("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
721 name=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
722 type=hyperdb.String())</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
723
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
724 <p>The "user" property indicates the user who submitted the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
725 file, the "name" property holds the original name of the file,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
726 and the "type" property holds the MIME type of the file as received.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
727
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
728 <h3>4.2. Item Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
729
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
730 <p>All items have the following standard properties:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
731
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
732 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
733 >title=hyperdb.String()
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
734 messages=hyperdb.Multilink("msg")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
735 files=hyperdb.Multilink("file")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
736 nosy=hyperdb.Multilink("user")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
737 superseder=hyperdb.Multilink("item")</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
738
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
739 <p>Also, two Date properties named "creation" and "activity" are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
740 fabricated by the Roundup database layer. By "fabricated" we
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
741 mean that no such properties are actually stored in the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
742 hyperdatabase, but when properties on items are requested, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
743 "creation" and "activity" properties are made available.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
744 The value of the "creation" property is the date when an item was
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
745 created, and the value of the "activity" property is the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
746 date when any property on the item was last edited (equivalently,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
747 these are the dates on the first and last records in the item's journal).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
748
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
749 <h3>4.3. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
750
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
751 <p>The interface to a Roundup database delegates most method
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752 calls to the hyperdatabase, except for the following
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
753 changes and additional methods.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
754
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
755 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
756 >class <strong>Database</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
758
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
759 def <strong>__init__</strong>(self, storagelocator, journaltag):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
760 """When the Roundup database is opened by a particular user,
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
761 the 'journaltag' is the id of the user's "user" item."""
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763 def <strong>getclass</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
764 """This method now returns an instance of either Class or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765 ItemClass depending on whether an item class is specified."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
766
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
767 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
768
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769 def <strong>getuid</strong>(self):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
770 """Return the id of the "user" item associated with the user
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771 that owns this connection to the hyperdatabase."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773 class <strong>Class</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 def <strong>create</strong>(self, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777 def <strong>set</strong>(self, **propvalues):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
778 def <strong>retire</strong>(self, itemid):
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 """These operations trigger detectors and can be vetoed. Attempts
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780 to modify the "creation" or "activity" properties cause a KeyError.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
783 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 def <strong>audit</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786 def <strong>react</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
787 """Register a detector (see below for more details)."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
788
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789 class <strong>ItemClass</strong>(Class):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 def <strong>__init__</strong>(self, db, classname, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793 """The newly-created class automatically includes the "messages",
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794 "files", "nosy", and "superseder" properties. If the 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
795 dictionary attempts to specify any of these properties or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
796 "creation" or "activity" property, a ValueError is raised."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
798 def <strong>get</strong>(self, itemid, propname):
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
799 def <strong>getprops</strong>(self):
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
800 """In addition to the actual properties on the item, these
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
801 methods provide the "creation" and "activity" properties."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
802
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
805 def <strong>addmessage</strong>(self, itemid, summary, text):
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
806 """Add a message to an item's mail spool.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
808 A new "msg" item is constructed using the current date, the
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809 user that owns the database connection as the author, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810 the specified summary text. The "files" and "recipients"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 fields are left empty. The given text is saved as the body
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
812 of the message and the item is appended to the "messages"
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813 field of the specified item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1091
diff changeset
816 def <strong>nosymessage</strong>(self, itemid, msgid):
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 """Send a message to the members of an item's nosy list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819 The message is sent only to users on the nosy list who are not
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820 already on the "recipients" list for the message. These users
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 are then added to the message's "recipients" list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
825 <h3>4.4. Default Schema</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
826
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
827 <p>The default schema included with Roundup turns it into a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828 typical software bug tracker. The database is set up like this:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
829
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
830 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
831 >pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
832 pri.setkey("name")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833 pri.create(name="critical", order="1")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 pri.create(name="urgent", order="2")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
835 pri.create(name="bug", order="3")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
836 pri.create(name="feature", order="4")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 pri.create(name="wish", order="5")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840 stat.setkey("name")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841 stat.create(name="unread", order="1")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 stat.create(name="deferred", order="2")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 stat.create(name="chatting", order="3")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844 stat.create(name="need-eg", order="4")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
845 stat.create(name="in-progress", order="5")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
846 stat.create(name="testing", order="6")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847 stat.create(name="done-cbb", order="7")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848 stat.create(name="resolved", order="8")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
849
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850 Class(db, "keyword", name=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 Class(db, "issue", fixer=hyperdb.Multilink("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853 topic=hyperdb.Multilink("keyword"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854 priority=hyperdb.Link("priority"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855 status=hyperdb.Link("status"))
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
856 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
858 <p>(The "order" property hasn't been explained yet. It
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
859 gets used by the Web user interface for sorting.)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
860
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
861 <p>The above isn't as pretty-looking as the schema specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
862 in the first-stage submission, but it could be made just as easy
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
863 with the addition of a convenience function like <tt>Choice</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
864 for setting up the "priority" and "status" classes:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
865
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
866 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
867 >def Choice(name, *options):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
868 cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
869 for i in range(len(options)):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
870 cl.create(name=option[i], order=i)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
871 return hyperdb.Link(name)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
872 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
874 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875 <h2>5. Detector Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
877 <p>Detectors are Python functions that are triggered on certain
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
878 kinds of events. The definitions of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
879 functions live in Python modules placed in a directory set aside
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
880 for this purpose. Importing the Roundup database module also
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
881 imports all the modules in this directory, and the <tt>init()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
882 function of each module is called when a database is opened to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
883 provide it a chance to register its detectors.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
885 <p>There are two kinds of detectors:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
886
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
887 <ul>
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
888 <li>an <em>auditor</em> is triggered just before modifying an item
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
889 <li>a <em>reactor</em> is triggered just after an item has been modified
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 <p>When the Roundup database is about to perform a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893 <tt>create()</tt>, <tt>set()</tt>, or <tt>retire()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
894 operation, it first calls any auditors that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895 have been registered for that operation on that class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
896 Any auditor may raise a <tt>Reject</tt> exception
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
897 to abort the operation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
898
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899 <p>If none of the auditors raises an exception, the database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
900 proceeds to carry out the operation. After it's done, it
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
901 then calls all of the reactors that have been registered
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
902 for the operation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
904 <h3>5.1. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
905
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906 <p>The <tt>audit()</tt> and <tt>react()</tt> methods
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
907 register detectors on a given class of items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910 >class Class:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
911 def <strong>audit</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912 """Register an auditor on this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
913
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
914 'event' should be one of "create", "set", or "retire".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
915 'detector' should be a function accepting four arguments.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
916 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
917
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
918 def <strong>react</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
919 """Register a reactor on this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
920
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
921 'event' should be one of "create", "set", or "retire".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
922 'detector' should be a function accepting four arguments.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
923 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
924 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
925
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
926 <p>Auditors are called with the arguments:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
927
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
928 <blockquote><pre><small
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
929 >audit(db, cl, itemid, newdata)</small></pre></blockquote>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
930
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
931 where <tt>db</tt> is the database, <tt>cl</tt> is an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
932 instance of Class or ItemClass within the database, and <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
933 is a dictionary mapping property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
934
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
935 For a <tt>create()</tt>
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
936 operation, the <tt>itemid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
937 contains all of the initial property values with which the item
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
938 is about to be created.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
939
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
940 For a <tt>set()</tt> operation, <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
941 contains only the names and values of properties that are about
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
942 to be changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
943
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
944 For a <tt>retire()</tt> operation, <tt>newdata</tt> is <tt>None</tt>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
945
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
946 <p>Reactors are called with the arguments:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
947
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
948 <blockquote><pre><small
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
949 >react(db, cl, itemid, olddata)</small></pre></blockquote>
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
950
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
951 where <tt>db</tt> is the database, <tt>cl</tt> is an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
952 instance of Class or ItemClass within the database, and <tt>olddata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
953 is a dictionary mapping property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
954
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
955 For a <tt>create()</tt>
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
956 operation, the <tt>itemid</tt> argument is the id of the
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
957 newly-created item and <tt>olddata</tt> is None.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
958
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
959 For a <tt>set()</tt> operation, <tt>olddata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
960 contains the names and previous values of properties that were changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
961
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
962 For a <tt>retire()</tt> operation, <tt>itemid</tt> is the
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
963 id of the retired item and <tt>olddata</tt> is <tt>None</tt>.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
964
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
965 <h3>5.2. Detector Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
966
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
967 <p>Here is an example of detectors written for a hypothetical
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
968 project-management application, where users can signal approval
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
969 of a project by adding themselves to an "approvals" list, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
970 a project proceeds when it has three approvals.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
971
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
972 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
973 ># Permit users only to add themselves to the "approvals" list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
974
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
975 def check_approvals(db, cl, id, newdata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
976 if newdata.has_key("approvals"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
977 if cl.get(id, "status") == db.status.lookup("approved"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
978 raise Reject, "You can't modify the approvals list " \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
979 "for a project that has already been approved."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
980 old = cl.get(id, "approvals")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
981 new = newdata["approvals"]
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
982 for uid in old:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
983 if uid not in new and uid != db.getuid():
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
984 raise Reject, "You can't remove other users from the "
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
985 "approvals list; you can only remove yourself."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
986 for uid in new:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
987 if uid not in old and uid != db.getuid():
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
988 raise Reject, "You can't add other users to the approvals "
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
989 "list; you can only add yourself."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
990
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
991 # When three people have approved a project, change its
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
992 # status from "pending" to "approved".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
993
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
994 def approve_project(db, cl, id, olddata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
995 if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
996 if cl.get(id, "status") == db.status.lookup("pending"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
997 cl.set(id, status=db.status.lookup("approved"))
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
998
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
999 def init(db):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1000 db.project.audit("set", check_approval)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1001 db.project.react("set", approve_project)</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1002 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1003
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1004 <p>Here is another example of a detector that can allow or prevent
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1005 the creation of new items. In this scenario, patches for a software
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1006 project are submitted by sending in e-mail with an attached file,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1007 and we want to ensure that there are <tt>text/plain</tt> attachments on
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1008 the message. The maintainer of the package can then apply the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1009 patch by setting its status to "applied".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1010
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1011 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1012 ># Only accept attempts to create new patches that come with patch files.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1013
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1014 def check_new_patch(db, cl, id, newdata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1015 if not newdata["files"]:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1016 raise Reject, "You can't submit a new patch without " \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1017 "attaching a patch file."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1018 for fileid in newdata["files"]:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1019 if db.file.get(fileid, "type") != "text/plain":
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1020 raise Reject, "Submitted patch files must be text/plain."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1021
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1022 # When the status is changed from "approved" to "applied", apply the patch.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1023
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1024 def apply_patch(db, cl, id, olddata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1025 if cl.get(id, "status") == db.status.lookup("applied") and \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1026 olddata["status"] == db.status.lookup("approved"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1027 # ...apply the patch...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1028
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1029 def init(db):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1030 db.patch.audit("create", check_new_patch)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1031 db.patch.react("set", apply_patch)</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1032 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1033
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1034 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1035 <h2>6. Command Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1036
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1037 <p>The command interface is a very simple and minimal interface,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1038 intended only for quick searches and checks from the shell prompt.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1039 (Anything more interesting can simply be written in Python using
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1040 the Roundup database module.)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1041
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1042 <h3>6.1. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1043
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1044 <p>A single command, <tt>roundup</tt>, provides basic access to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1045 the hyperdatabase from the command line.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1046
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1047 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1048 <li><tt>roundup&nbsp;get&nbsp;</tt>[<tt>-list</tt>]<tt>&nbsp;</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1049 ><em>designator</em>[<tt>,</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1050 ><em>designator</em><tt>,</tt>...]<tt>&nbsp;</tt><em>propname</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1051 <li><tt>roundup&nbsp;set&nbsp;</tt><em>designator</em>[<tt>,</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1052 ><em>designator</em><tt>,</tt>...]<tt>&nbsp;</tt><em>propname</em
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1053 ><tt>=</tt><em>value</em> ...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1054 <li><tt>roundup&nbsp;find&nbsp;</tt>[<tt>-list</tt>]<tt>&nbsp;</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1055 ><em>classname</em><tt>&nbsp;</tt><em>propname</em>=<em>value</em> ...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1056 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1057
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1058 <p>Property values are represented as strings in command arguments
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1059 and in the printed results:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1060
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1061 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1062 <li>Strings are, well, strings.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1063
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1064 <li>Date values are printed in the full date format in the local
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1065 time zone, and accepted in the full format or any of the partial
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1066 formats explained above.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1067
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1068 <li>Link values are printed as item designators. When given as
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1069 an argument, item designators and key strings are both accepted.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1070
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1071 <li>Multilink values are printed as lists of item designators
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1072 joined by commas. When given as an argument, item designators
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1073 and key strings are both accepted; an empty string, a single item,
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1074 or a list of items joined by commas is accepted.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1075 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1076
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1077 <p>When multiple items are specified to the
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1078 <tt>roundup&nbsp;get</tt> or <tt>roundup&nbsp;set</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1079 commands, the specified properties are retrieved or set
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1080 on all the listed items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1081
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1082 <p>When multiple results are returned by the <tt>roundup&nbsp;get</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1083 or <tt>roundup&nbsp;find</tt> commands, they are printed one per
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1084 line (default) or joined by commas (with the <tt>-list</tt>) option.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1085
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1086 <h3>6.2. Usage Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1087
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1088 <p>To find all messages regarding in-progress issues that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1089 contain the word "spam", for example, you could execute the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1090 following command from the directory where the database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1091 dumps its files:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1092
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1093 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1094 >shell% <span class="input">for issue in `roundup find issue status=in-progress`; do</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1095 &gt; <span class="input">grep -l spam `roundup get $issue messages`</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1096 &gt; <span class="input">done</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1097 <span class="output">msg23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1098 msg49
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1099 msg50
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1100 msg61</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1101 shell%</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1102
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1103 <p>Or, using the <tt>-list</tt> option, this can be written as a single command:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1104
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1105 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1106 >shell% <span class="input">grep -l spam `roundup get \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1107 \`roundup find -list issue status=in-progress\` messages`</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1108 <span class="output">msg23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1109 msg49
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1110 msg50
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1111 msg61</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1112 shell%</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1113
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1114 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1115 <h2>7. E-mail User Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1116
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1117 <p>The Roundup system must be assigned an e-mail address
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1118 at which to receive mail. Messages should be piped to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1119 the Roundup mail-handling script by the mail delivery
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1120 system (e.g. using an alias beginning with "|" for sendmail).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1121
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1122 <h3>7.1. Message Processing</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1123
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1124 <p>Incoming messages are examined for multiple parts.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1125 In a <tt>multipart/mixed</tt> message or part, each subpart is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1126 extracted and examined. In a <tt>multipart/alternative</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1127 message or part, we look for a <tt>text/plain</tt> subpart and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1128 ignore the other parts. The <tt>text/plain</tt> subparts are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1129 assembled to form the textual body of the message, to
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1130 be stored in the file associated with a "msg" class item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1131 Any parts of other types are each stored in separate
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1132 files and given "file" class items that are linked to
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1133 the "msg" item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1134
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1135 <p>The "summary" property on message items is taken from
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1136 the first non-quoting section in the message body.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1137 The message body is divided into sections by blank lines.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1138 Sections where the second and all subsequent lines begin
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1139 with a "&gt;" or "|" character are considered "quoting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1140 sections". The first line of the first non-quoting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1141 section becomes the summary of the message.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1142
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1143 <p>All of the addresses in the To: and Cc: headers of the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1144 incoming message are looked up among the user items, and
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1145 the corresponding users are placed in the "recipients"
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1146 property on the new "msg" item. The address in the From:
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1147 header similarly determines the "author" property of the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1148 new "msg" item.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1149 The default handling for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1150 addresses that don't have corresponding users is to create
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1151 new users with no passwords and a username equal to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1152 address. (The web interface does not permit logins for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1153 users with no passwords.) If we prefer to reject mail from
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1154 outside sources, we can simply register an auditor on the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1155 "user" class that prevents the creation of user items with
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1156 no passwords.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1157
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1158 <p>The subject line of the incoming message is examined to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1159 determine whether the message is an attempt to create a new
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1160 item or to discuss an existing item. A designator enclosed
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1161 in square brackets is sought as the first thing on the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1162 subject line (after skipping any "Fwd:" or "Re:" prefixes).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1163
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1164 <p>If an item designator (class name and id number) is found
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1165 there, the newly created "msg" item is added to the "messages"
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1166 property for that item, and any new "file" items are added to
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1167 the "files" property for the item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1168
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1169 <p>If just an item class name is found there, we attempt to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1170 create a new item of that class with its "messages" property
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1171 initialized to contain the new "msg" item and its "files"
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1172 property initialized to contain any new "file" items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1173
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1174 <p>Both cases may trigger detectors (in the first case we
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1175 are calling the <tt>set()</tt> method to add the message to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1176 item's spool; in the second case we are calling the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1177 <tt>create()</tt> method to create a new item). If an auditor
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1178 raises an exception, the original message is bounced back to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1179 the sender with the explanatory message given in the exception.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1180
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1181 <h3>7.2. Nosy Lists</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1182
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1183 <p>A standard detector is provided that watches for additions
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1184 to the "messages" property. When a new message is added, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1185 detector sends it to all the users on the "nosy" list for the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1186 item that are not already on the "recipients" list of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1187 message. Those users are then appended to the "recipients"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1188 property on the message, so multiple copies of a message
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1189 are never sent to the same user. The journal recorded by
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1190 the hyperdatabase on the "recipients" property then provides
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1191 a log of when the message was sent to whom.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1192
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1193 <h3>7.3. Setting Properties</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1194
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1195 <p>The e-mail interface also provides a simple way to set
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1196 properties on items. At the end of the subject line,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1197 <em>propname</em><tt>=</tt><em>value</em> pairs can be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1198 specified in square brackets, using the same conventions
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1199 as for the <tt>roundup&nbsp;set</tt> shell command.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1200
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1201 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1202 <h2>8. Web User Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1203
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1204 <p>The web interface is provided by a CGI script that can be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1205 run under any web server. A simple web server can easily be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1206 built on the standard <tt>CGIHTTPServer</tt> module, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1207 should also be included in the distribution for quick
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1208 out-of-the-box deployment.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1209
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1210 <p>The user interface is constructed from a number of template
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1211 files containing mostly HTML. Among the HTML tags in templates
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1212 are interspersed some nonstandard tags, which we use as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1213 placeholders to be replaced by properties and their values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1214
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1215 <h3>8.1. Views and View Specifiers</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1216
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1217 <p>There are two main kinds of views: index views and item views.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1218 An index view displays a list of items of a particular class,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1219 optionally sorted and filtered as requested. An item view
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1220 presents the properties of a particular item for editing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1221 and displays the message spool for the item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1222
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1223 <p>A <em>view specifier</em> is a string that specifies
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1224 all the options needed to construct a particular view.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1225 It goes after the URL to the Roundup CGI script or the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1226 web server to form the complete URL to a view. When the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1227 result of selecting a link or submitting a form takes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1228 the user to a new view, the Web browser should be redirected
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1229 to a canonical location containing a complete view specifier
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1230 so that the view can be bookmarked.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1231
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1232 <h3>8.2. Displaying Properties</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1233
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1234 <p>Properties appear in the user interface in three contexts:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1235 in indices, in editors, and as filters. For each type of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1236 property, there are several display possibilities. For example,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1237 in an index view, a string property may just be printed as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1238 a plain string, but in an editor view, that property should
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1239 be displayed in an editable field.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1240
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1241 <p>The display of a property is handled by functions in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1242 a <tt>displayers</tt> module. Each function accepts at
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1243 least three standard arguments -- the database, class name,
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1244 and item id -- and returns a chunk of HTML.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1245
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1246 <p>Displayer functions are triggered by <tt>&lt;display&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1247 tags in templates. The <tt>call</tt> attribute of the tag
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1248 provides a Python expression for calling the displayer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1249 function. The three standard arguments are inserted in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1250 front of the arguments given. For example, the occurrence of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1251
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1252 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1253 > &lt;display call="plain('status', max=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1254 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1255
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1256 in a template triggers a call to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1257
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1258 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1259 > plain(db, "issue", 13, "status", max=30)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1260 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1261
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1262 when displaying item 13 in the "issue" class. The displayer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1263 functions can accept extra arguments to further specify
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1264 details about the widgets that should be generated. By defining new
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1265 displayer functions, the user interface can be highly customized.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1266
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1267 <p>Some of the standard displayer functions include:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1268
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1269 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1270 <li><strong>plain</strong>: display a String property directly;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1271 display a Date property in a specified time zone with an option
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1272 to omit the time from the date stamp; for a Link or Multilink
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1273 property, display the key strings of the linked items (or the
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1274 ids if the linked class has no key property)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1275
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1276 <li><strong>field</strong>: display a property like the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1277 <strong>plain</strong> displayer above, but in a text field
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1278 to be edited
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1279
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1280 <li><strong>menu</strong>: for a Link property, display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1281 a menu of the available choices
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1282
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1283 <li><strong>link</strong>: for a Link or Multilink property,
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1284 display the names of the linked items, hyperlinked to the
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1285 item views on those items
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1286
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1287 <li><strong>count</strong>: for a Multilink property, display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1288 a count of the number of links in the list
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1289
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1290 <li><strong>reldate</strong>: display a Date property in terms
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1291 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1292
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1293 <li><strong>download</strong>: show a Link("file") or Multilink("file")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1294 property using links that allow you to download files
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1295
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1296 <li><strong>checklist</strong>: for a Link or Multilink property,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1297 display checkboxes for the available choices to permit filtering
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1298 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1299
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1300 <h3>8.3. Index Views</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1301
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1302 <p>An index view contains two sections: a filter section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1303 and an index section.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1304 The filter section provides some widgets for selecting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1305 which items appear in the index. The index section is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1306 a table of items.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1307
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1308 <h4>8.3.1. Index View Specifiers</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1309
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1310 <p>An index view specifier looks like this (whitespace
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1311 has been added for clarity):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1312
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1313 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1314 >/issue?status=unread,in-progress,resolved&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1315 topic=security,ui&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1316 :group=+priority&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1317 :sort=-activity&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1318 :filters=status,topic&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1319 :columns=title,status,fixer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1320 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1321
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1322 <p>The index view is determined by two parts of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1323 specifier: the layout part and the filter part.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1324 The layout part consists of the query parameters that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1325 begin with colons, and it determines the way that the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1326 properties of selected items are displayed.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1327 The filter part consists of all the other query parameters,
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1328 and it determines the criteria by which items
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1329 are selected for display.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1330
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1331 <p>The filter part is interactively manipulated with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1332 the form widgets displayed in the filter section. The
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1333 layout part is interactively manipulated by clicking
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1334 on the column headings in the table.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1335
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1336 <p>The filter part selects the <em>union</em> of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1337 sets of items with values matching any specified Link
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1338 properties and the <em>intersection</em> of the sets
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1339 of items with values matching any specified Multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1340 properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1341
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1342 <p>The example specifies an index of "issue" items.
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1343 Only items with a "status" of <em>either</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1344 "unread" or "in-progres" or "resolved" are displayed,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1345 and only items with "topic" values including <em>both</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1346 "security" <em>and</em> "ui" are displayed. The items
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1347 are grouped by priority, arranged in ascending order;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1348 and within groups, sorted by activity, arranged in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1349 descending order. The filter section shows filters
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1350 for the "status" and "topic" properties, and the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1351 table includes columns for the "title", "status", and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1352 "fixer" properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1353
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1354 <p>Associated with each item class is a default
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1355 layout specifier. The layout specifier in the above
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1356 example is the default layout to be provided with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1357 the default bug-tracker schema described above in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1358 section 4.4.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1359
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1360 <h4>8.3.2. Filter Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1361
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1362 <p>The template for a filter section provides the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1363 filtering widgets at the top of the index view.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1364 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1365 tags are included or omitted depending on whether the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1366 view specifier requests a filter for a particular property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1367
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1368 <p>Here's a simple example of a filter template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1369
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1370 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1371 >&lt;property name=status&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1372 &lt;display call="checklist('status')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1373 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1374 &lt;br&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1375 &lt;property name=priority&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1376 &lt;display call="checklist('priority')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1377 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1378 &lt;br&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1379 &lt;property name=fixer&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1380 &lt;display call="menu('fixer')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1381 &lt;/property&gt;</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1382
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1383 <h4>8.3.3. Index Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1384
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1385 <p>The template for an index section describes one row of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1386 the index table.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1387 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1388 tags are included or omitted depending on whether the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1389 view specifier requests a column for a particular property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1390 The table cells should contain <tt>&lt;display&gt;</tt> tags
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1391 to display the values of the item's properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1392
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1393 <p>Here's a simple example of an index template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1394
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1395 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1396 >&lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1397 &lt;property name=title&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1398 &lt;td&gt;&lt;display call="plain('title', max=50)"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1399 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1400 &lt;property name=status&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1401 &lt;td&gt;&lt;display call="plain('status')"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1402 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1403 &lt;property name=fixer&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1404 &lt;td&gt;&lt;display call="plain('fixer')"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1405 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1406 &lt;/tr&gt;</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1407
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1408 <h4>8.3.4. Sorting</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1409
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1410 <p>String and Date values are sorted in the natural way.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1411 Link properties are sorted according to the value of the
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1412 "order" property on the linked items if it is present; or
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1413 otherwise on the key string of the linked items; or
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1414 finally on the item ids. Multilink properties are
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1415 sorted according to how many links are present.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1416
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1417 <h3>8.4. Item Views</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1418
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1419 <p>An item view contains an editor section and a spool section.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1420 At the top of an item view, links to superseding and superseded
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1421 items are always displayed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1422
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1423 <h4>8.4.1. Item View Specifiers</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1424
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1425 <p>An item view specifier is simply the item's designator:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1426
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1427 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1428 >/patch23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1429 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1430
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1431 <h4>8.4.2. Editor Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1432
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1433 <p>The editor section is generated from a template
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1434 containing <tt>&lt;display&gt;</tt> tags to insert
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1435 the appropriate widgets for editing properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1436
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1437 <p>Here's an example of a basic editor template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1438
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1439 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1440 >&lt;table&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1441 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1442 &lt;td colspan=2&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1443 &lt;display call="field('title', size=60)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1444 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1445 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1446 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1447 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1448 &lt;display call="field('fixer', size=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1449 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1450 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1451 &lt;display call="menu('status')&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1452 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1453 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1454 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1455 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1456 &lt;display call="field('nosy', size=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1457 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1458 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1459 &lt;display call="menu('priority')&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1460 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1461 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1462 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1463 &lt;td colspan=2&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1464 &lt;display call="note()"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1465 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1466 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1467 &lt;/table&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1468 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1469
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1470 <p>As shown in the example, the editor template can also
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1471 request the display of a "note" field, which is a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1472 text area for entering a note to go along with a change.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1473
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1474 <p>When a change is submitted, the system automatically
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1475 generates a message describing the changed properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1476 The message displays all of the property values on the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1477 item and indicates which ones have changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1478 An example of such a message might be this:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1479
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1480 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1481 >title: Polly Parrot is dead
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1482 priority: critical
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1483 status: unread -&gt; in-progress
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1484 fixer: (none)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1485 keywords: parrot,plumage,perch,nailed,dead
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1486 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1487
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1488 <p>If a note is given in the "note" field, the note is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1489 appended to the description. The message is then added
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1490 to the item's message spool (thus triggering the standard
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1491 detector to react by sending out this message to the nosy list).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1492
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1493 <h4>8.4.3. Spool Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1494
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1495 <p>The spool section lists messages in the item's "messages"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1496 property. The index of messages displays the "date", "author",
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1497 and "summary" properties on the message items, and selecting a
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1498 message takes you to its content.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1499
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1500 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1501 <h2>9. Deployment Scenarios</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1502
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1503 <p>The design described above should be general enough
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1504 to permit the use of Roundup for bug tracking, managing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1505 projects, managing patches, or holding discussions. By
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 108
diff changeset
1506 using items of multiple types, one could deploy a system
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1507 that maintains requirement specifications, catalogs bugs,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1508 and manages submitted patches, where patches could be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1509 linked to the bugs and requirements they address.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1510
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1511 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1512 <h2>10. Acknowledgements</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1513
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1514 <p>My thanks are due to Christy Heyl for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1515 reviewing and contributing suggestions to this paper
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1516 and motivating me to get it done, and to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1517 Jesse Vincent, Mark Miller, Christopher Simons,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1518 Jeff Dunmall, Wayne Gramlich, and Dean Tribble for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1519 their assistance with the first-round submission.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1520 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1521 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1522 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1523
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1524 <p>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1525
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1526 <center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1527 <table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1528 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1529 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/index.html"><b>[Home]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1530 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/faq.html"><b>[FAQ]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1531 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/license.html"><b>[License]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1532 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/contest-rules.html"><b>[Rules]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1533 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_config/"><b>[Configure]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1534 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_build/"><b>[Build]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1535 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_test/"><b>[Test]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1536 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_track/"><b>[Track]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1537 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/biblio.html"><b>[Resources]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1538 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/lists/"><b>[Archives]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1539 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1540 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1541 </center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1542
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1543 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1544 <center>Last modified 2001/04/06 11:50:59.9063 US/Mountain</center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1545 </BODY>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1546 </HTML>
Roundup Issue Tracker: http://roundup-tracker.org/