Mercurial > p > roundup > code

annotate doc/spec.html @ 818:254b8d112eec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cleaned up the indexer code: - it splits more words out (much simpler, faster splitter) - removed code we'll never use (roundup.roundup_indexer has the full implementation, and replaces roundup.indexer) - only index text/plain and rfc822/message (ideas for other text formats to index are welcome) - added simple unit test for indexer. Needs more tests for regression.
author Richard Jones <richard@users.sourceforge.net>
date Mon, 08 Jul 2002 06:58:15 +0000
parents 944bb5255eaf
children d870139aeb5c
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 <li>Nodes and Classes
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 records which we call <em>nodes</em>.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
338 <h3>3.2. Nodes and Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340 <p>Nodes contain data in <em>properties</em>. To Python, these
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.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
342 Each node belongs to a <em>class</em> which defines the names
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
344 and modification of classes as well as nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
348 <p>Each node has a numeric identifier which is unique among
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349 nodes in its class. The nodes are numbered sequentially
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>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352 for a node is a way to identify a node in the database, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353 consists of the name of the node's class concatenated with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354 the node's numeric identifier.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357 node created in class "spam" has id 1 and designator "spam1".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 The first node created in class "eggs" also has id 1 but has
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
359 the distinct designator "eggs1". Node designators are
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 <li>A <em>Link</em> property refers to a single other node
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;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 the value is an integer, the id of the chosen node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 <li>A <em>Multilink</em> property refers to possibly many nodes
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 nodes in a specified class."""
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414 to nodes in a specified class."""
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>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450 """The handle to a particular class of nodes in a hyperdatabase."""
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460 # Editing nodes:
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 """Create a new node of this class and return its id.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472 property does not refer to a valid node, an IndexError is raised.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475 def <strong>get</strong>(self, nodeid, propname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476 """Get the value of a property on an existing node of this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
478 'nodeid' must be the id of an existing node of this class or an
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483 def <strong>set</strong>(self, nodeid, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
484 """Modify a property on an existing node of this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486 'nodeid' must be the id of an existing node of this class or an
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 property contains an invalid node id, a ValueError is raised.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496 def <strong>retire</strong>(self, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 """Retire a node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 The properties on the node remain available from the get() method,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 and the node's id is never reused. Retired nodes are not returned
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 by the find(), list(), or lookup() methods, and other nodes may
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505 def <strong>history</strong>(self, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 """Retrieve the journal of edits on a particular node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508 'nodeid' must be the id of an existing node of this class or an
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520 'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
524 # Locating nodes:
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
531 all existing nodes must be unique or a ValueError is raised.
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538 """Locate a particular node by its key property and return its id.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 the nodes in this class, the matching node's id is returned;
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546 def <strong>find</strong>(self, propname, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 """Get the ids of nodes in this class which link to a given node.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 property, or a TypeError is raised. 'nodeid' must be the id of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 an existing node in the class linked to by the given property,
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
557 """Return a list of the ids of the active nodes in this class."""
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 """Get the number of nodes in this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562 If the returned integer is 'numnodes', the ids of all the nodes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
563 in this class run from 1 to numnodes, and numnodes+1 will be the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564 id of the next node to be created in this class.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
652 set to a new list of nodes, the hyperdatabase compares the old
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.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654 The journal records "unlink" events for all the nodes that appear
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
657 all the nodes that appear in the new list but not in the old list.
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>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
666 The Roundup database layer adds detectors and user nodes,
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
672 of nodes that are not items.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
676 <p>Users are stored in the hyperdatabase as nodes of
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
687 <p>E-mail messages are represented by hyperdatabase nodes of class "msg".
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
692 saved in a file named after the message node designator (e.g. "msg23")
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
694 stored separately and associated with "file" nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
706 (a "user" node must exist in the hyperdatabase for any messages
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
714 nodes of class "file". Like e-mail messages, the file content
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,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
716 named after the file node designator (e.g. "file17").
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,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
761 the 'journaltag' is the id of the user's "user" node."""
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 """Return the id of the "user" node associated with the user
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 def <strong>retire</strong>(self, nodeid):
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 def <strong>get</strong>(self, nodeid, propname):
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):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800 """In addition to the actual properties on the node, these
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805 def <strong>addmessage</strong>(self, nodeid, summary, text):
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
808 A new "msg" node is constructed using the current date, the
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812 of the message and the node is appended to the "messages"
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816 def <strong>sendmessage</strong>(self, nodeid, msgid):
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>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
888 <li>an <em>auditor</em> is triggered just before modifying an node
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
889 <li>a <em>reactor</em> is triggered just after an node has been modified
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
907 register detectors on a given class of nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
929 >audit(db, cl, nodeid, newdata)</small></pre></blockquote>
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>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
936 operation, the <tt>nodeid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
937 contains all of the initial property values with which the node
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
949 >react(db, cl, nodeid, olddata)</small></pre></blockquote>
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>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
956 operation, the <tt>nodeid</tt> argument is the id of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
957 newly-created node and <tt>olddata</tt> is None.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
962 For a <tt>retire()</tt> operation, <tt>nodeid</tt> is the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
963 id of the retired node and <tt>olddata</tt> is <tt>None</tt>.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1005 the creation of new nodes. In this scenario, patches for a software
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1068 <li>Link values are printed as node designators. When given as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1069 an argument, node designators and key strings are both accepted.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1070
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1071 <li>Multilink values are printed as lists of node designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1072 joined by commas. When given as an argument, node designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1073 and key strings are both accepted; an empty string, a single node,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1074 or a list of nodes joined by commas is accepted.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1077 <p>When multiple nodes are specified to the
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1080 on all the listed nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1130 be stored in the file associated with a "msg" class node.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1132 files and given "file" class nodes that are linked to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1133 the "msg" node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1134
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1135 <p>The "summary" property on message nodes is taken from
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1144 incoming message are looked up among the user nodes, and
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"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1146 property on the new "msg" node. The address in the From:
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1148 new "msg" node.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1155 "user" class that prevents the creation of user nodes with
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1165 there, the newly created "msg" node is added to the "messages"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1166 property for that item, and any new "file" nodes are added to
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1171 initialized to contain the new "msg" node and its "files"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1172 property initialized to contain any new "file" nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1177 <tt>create()</tt> method to create a new node). If an auditor
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,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1244 and node id -- and returns a chunk of HTML.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1273 property, display the key strings of the linked nodes (or the
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,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1284 display the names of the linked nodes, hyperlinked to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1285 item views on those nodes
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1326 properties of selected nodes are displayed.
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,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1328 and it determines the criteria by which nodes
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1342 <p>The example specifies an index of "issue" nodes.
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1412 "order" property on the linked nodes if it is present; or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1413 otherwise on the key string of the linked nodes; or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1414 finally on the node ids. Multilink properties are
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",
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1497 and "summary" properties on the message nodes, and selecting a
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
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1506 using nodes of multiple types, one could deploy a system
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/