diff --git a/scheme/httpd/surflets/packages.scm b/scheme/httpd/surflets/packages.scm
index 556bf54..54c6464 100644
--- a/scheme/httpd/surflets/packages.scm
+++ b/scheme/httpd/surflets/packages.scm
@@ -23,52 +23,143 @@
surflet-response-headers
surflet-response-data))
+;; SUrflet-requests as expected from the surflet handler
+(define-interface surflet-handler/requests-interface
+ (export make-surflet-request ;FIMXE? unusable for user
+ surflet-request?
+ surflet-request-request
+ surflet-request-input-port
+ surflet-request-method
+ surflet-request-uri
+ surflet-request-url
+ surflet-request-version
+ surflet-request-headers
+ surflet-request-socket))
+
+(define-interface surflets/error-interface
+ (export send-error ;send error response
+ (status-code :syntax))) ;from httpd-responses
+
;; Use for SUrflets
-(define-interface surflet-handler/surflets-interface
+(define-interface surflet-handler/primitives-interface
(compound-interface
surflet-handler/responses-interface
+ surflet-handler/requests-interface
+ surflets/error-interface
(export send/suspend ;send and suspend
send/finish ;send and finish
send ;just send (no finish, no suspend)
- send-error ;send error response
- set-session-data!
- get-session-data
- adjust-timeout! ;adjusts timeout of current session
)))
-;; Use for adminstration of the Surflet Handler
-(define-interface surflet-handler/admin-interface
- (export get-loaded-surflets
- unload-surflet
- options-session-lifetime
- options-cache-surflets?
- options-surflet-path
- set-options-session-lifetime!
- set-options-cache-surflets?!
+;; Send HTML-Strings (for advanced user)
+(define-interface surflets/send-html-string-interface
+ (export send-html-string/suspend
+ send-html-string/finish
+ send-html-string))
+;; Extensions/Exports to/from Olegs SSAX library
+(define-interface surflets/sxml-interface
+ (export display-low-level-sxml
+ sxml->string
+ sxml->string/internal
+ sxml-attribute?
+ default-rule
+ text-rule
+ attribute-rule))
+
+;; SUrflets' extensions to SXML
+(define-interface surflets/surflet-sxml-interface
+ (export surflet-sxml->low-level-sxml
+ surflet-sxml-rules
+ surflet-form-rule
+ default-rules
+ plain-html-rule
+ url-rule))
+
+;; Use for advanced users: make your own conversion rules.
+(define-interface surflets/my-sxml-interface
+ (compound-interface
+ surflets/send-html-string-interface
+ surflets/sxml-interface
+ surflets/surflet-sxml-interface))
+
+(define-interface surflets/continuations-interface
+ (export get-continuations
+ delete-continuation!))
+
+;; Access to session-id and continuation-id
+(define-interface surflets/ids-interface
+ (export my-session-id
+ my-continuation-id
+ my-ids
+ instance-session-id))
+
+;; Use for advanced users: access to your sessions and continuations
+;; and continuations (currently you get access to all sessions; this
+;; should and will be restricted in the future)
+(define-interface surflets/my-sessions-interface
+ (compound-interface
+ surflets/ids-interface
+ surflets/continuations-interface
+ (export get-session
+ ;; That would be too much:
+ ;; get-sessions
+ delete-session!
+ get-session-data
+ set-session-data!
+ instance-session-id
+ session-adjust-timeout!
+ adjust-timeout!
+ session-alive?
+ session-surflet-name
+ options-session-lifetime
+ options-cache-surflets?)))
+
+(define-interface surflets/sessions-interface
+ (export get-session
get-sessions
+ delete-session!
+ get-session-data
+ set-session-data!
+ instance-session-id
+ session-adjust-timeout!
+ adjust-timeout!
session-alive?
session-surflet-name
+ ;; FIXME: This is too much and should be restricted:
session-memo
session-continuation-table
session-continuation-table-lock
- session-continuation-counter
- delete-session!
+ session-continuation-counter))
- session-adjust-timeout!
- adjust-timeout!
+(define-interface surflet-handler/surflets-interface
+ (export get-loaded-surflets
+ unload-surflet))
- get-continuations
- delete-continuation!
+(define-interface surflet-handler/options-interface
+ (export options-session-lifetime
+ options-cache-surflets?
+ options-surflet-path
+ set-options-session-lifetime!
+ set-options-cache-surflets?!))
- instance-session-id
-
- resume-url?
+(define-interface surflet-handler/resume-url-interface
+ (export resume-url?
resume-url-ids
resume-url-session-id
resume-url-continuation-id))
+;; Use for adminstration of the Surflet Handler
+(define-interface surflet-handler/admin-interface
+ (compound-interface
+ surflet-handler/surflets-interface
+ surflets/sessions-interface
+ surflets/continuations-interface
+ surflet-handler/resume-url-interface
+ surflet-handler/options-interface
+))
+
;; THE interface that SUrflets use.
(define-interface surflet-interface
(export main)) ; MAIN gets one parameter, the REQUEST
@@ -141,18 +232,7 @@
thread-safe-counter-next!
thread-safe-counter?))
-;; SUrflet-requests as expected from the surflet handler
-(define-interface surflet-requests-interface
- (export make-surflet-request
- surflet-request?
- surflet-request-request
- surflet-request-input-port
- surflet-request-method
- surflet-request-uri
- surflet-request-url
- surflet-request-version
- surflet-request-headers
- surflet-request-socket))
+
;; These two are from Martin Gasbichler:
(define-interface rt-module-language-interface
@@ -177,14 +257,7 @@
(export typed-optionals
(optionals :syntax)))
-;; Extensions/Exports to/from Olegs SSAX library
-(define-interface surflets/sxml-interface
- (export display-low-level-sxml
- sxml->string
- sxml-attribute?
- default-rule
- text-rule
- attribute-rule))
+
;; Input-fields as Scheme objects
(define-interface surflets/input-fields-interface
@@ -213,22 +286,6 @@
(export *input-field-trigger*
input-field-html-tree))
-;; SUrflets' extensions to SXML
-(define-interface surflets/surflet-sxml-interface
- (export surflet-sxml->low-level-sxml
- surflet-sxml-rules
- surflet-form-rule
- default-rules
- plain-html-rule
- url-rule))
-
-;; Access to session-id and continuation-id
-(define-interface surflets/ids-interface
- (export my-session-id
- my-continuation-id
- my-ids
- instance-session-id))
-
;; Some utilities
(define-interface surflets/utilities-interface
(export form-query-list
@@ -263,33 +320,39 @@
extract-bindings
extract-single-binding))
-;; HTML-Extensions to send/suspend et al.
+;; HTML-Extensions to send/suspend et al. (for basic user)
(define-interface surflets/send-html-interface
(export send-html/suspend
send-html/finish
send-html))
-;; Helping functions for surflets
+
+;; Helping functions for surflets (for basic user)
(define-interface surflets-interface
(compound-interface
- surflet-handler/surflets-interface
- surflets/sxml-interface
- surflets/surflet-sxml-interface
+; surflet-handler/surflets-interface;
+; surflets/sxml-interface
+; surflets/surflet-sxml-interface
surflets/send-html-interface
surflets/input-fields-interface
surflets/addresses-interface
surflets/returned-via-interface
surflets/bindings-interface))
-
;;; Structures
;; structures from SUrflet Handler
(define-structures
((surflet-handler surflet-handler-interface)
(surflet-handler/surflets surflet-handler/surflets-interface)
+ (surflet-handler/options surflet-handler/options-interface)
+ (surflet-handler/resume-url surflet-handler/resume-url-interface)
(surflet-handler/admin surflet-handler/admin-interface)
- (surflet-handler/responses surflet-handler/responses-interface))
+ (surflet-handler/primitives surflet-handler/primitives-interface)
+ (surflet-handler/responses surflet-handler/responses-interface)
+ (surflets/sessions surflets/sessions-interface)
+ (surflets/continuations surflets/continuations-interface)
+ (surflets/error surflets/error-interface))
(open define-record-types ;DEFINE-RECORD-TYPE
handle-fatal ;WITH-FATAL-ERROR-HANDLER* et al.
handle-fatal-error
@@ -319,15 +382,19 @@
;; SUrflets library of helping functions
(define-structure surflets surflets-interface
- (open surflet-handler/surflets
- surflets/sxml
- surflets/surflet-sxml
- surflets/send-html
+ (open surflets/send-html
surflets/input-fields
surflets/addresses
surflets/returned-via
surflets/bindings))
+;; SUrflets library for advanced users: make and use your own
+;; conversion rules.
+(define-structure surflets/my-sxml surflets/my-sxml-interface
+ (open surflets/send-html-string
+ surflets/sxml
+ surflets/surflet-sxml))
+
;; Shift-Reset
(define-structure shift-reset shift-reset-interface
(open scheme
@@ -371,8 +438,14 @@
define-record-types)
(files thread-safe-counter))
-;; SUrflet-requests as expected from the SUrflet handler
-(define-structure surflet-requests surflet-requests-interface
+;; SUrflet-requests as expected from the SUrflet handler
+;;; We have two names for the same thing to ease the use of structure
+;;; names: requests seem to be part of the surflet-handler, but are
+;;; actually seperate files. If you know everything about SUrflets,
+;;; you use `surlfet-requests'.
+(define-structures
+ ((surflet-handler/requests surflet-handler/requests-interface)
+ (surflet-requests surflet-handler/requests-interface))
(open scheme
define-record-types
httpd-requests)
@@ -442,7 +515,7 @@
(define-structure surflets/utilities surflets/utilities-interface
(open scheme
parse-html-forms
- (subset surflet-handler/surflets (send/suspend)))
+ (subset surflet-handler/primitives (send/suspend)))
(files utilities))
@@ -482,10 +555,11 @@
(subset sunet-utilities (get-header)))
(files bindings))
-(define-structure surflets/send-html surflets/send-html-interface
+(define-structures
+ ((surflets/send-html surflets/send-html-interface)
+ (surflets/send-html-string surflets/send-html-string-interface))
(open scheme
- (subset httpd-responses (status-code))
- surflet-handler/surflets
+ surflet-handler/primitives
surflets/sxml
surflets/surflet-sxml)
(files send-html))
diff --git a/scheme/httpd/surflets/surflets-structures.txt b/scheme/httpd/surflets/surflets-structures.txt
new file mode 100644
index 0000000..1ca7b11
--- /dev/null
+++ b/scheme/httpd/surflets/surflets-structures.txt
@@ -0,0 +1,188 @@
+We have three basic layers of structures: -*- Outline -*-
+
+* Overview
+(a) Basic User surflets, simple-surflet-api
+(b) Advanced User surflets/my-sxml, surflets/my-sessions,
+ surflet-handler/primitives
+(c) Administrative User surflet-handler/admin, profiling
+
+The fourth layer:
+(d) Various surflets/outdaters, surflets/utilities
+
+Finally, there is a HOWTO added, that describes how you can use your
+own rules.
+
+* (a) Basic User
+** structures: (1) surflets
+ provides: . sending of html represented by surflet-sxml
+ . using special tags in its surflet-sxml:
+ url, plain-html, surflet-form
+ . input-fields, input-field-value,...
+ . get-bindings, extract-bindings, ...
+ . make-address, make-annotated-address, ...
+ . returned-via?, case-returned-via, ...
+ surflets is splitted in several parts, that can
+ be loaded independently from each other.
+
+** structures: (2) simple-surflet-api
+ provides: . PLT like generation of simple web pages:
+ . single-query, form-query, inform-page,
+ final-page
+ . make-password, make-number...
+
+
+* (b) Advanced User
+** structures: (1) surflets/my-sxml
+ provides: . generating and sending of own sxml,
+ see HOWTO below
+ . send-html-string/suspend...
+ . sxml-rules...
+ . sxml->string
+ . surflet-sxml-rules...
+ . surflet-sxml->low-level-sxml
+
+** structures: (2) surflets/my-sessions
+ provides: . Everything needed to administrate your own
+ sessions and continuations.
+ (This represents the access to the sessions of
+ one surflet. However, you currently have
+ access to all sessions. This will be
+ restricted in the future.)
+ . my-session-id, my-continuation-id,
+ instance-session-id
+ . get-session, delete-session!
+ . get-continuation, delete-continuation!
+ . session-adjust-timeout!, adjust-timeout!
+ . session-alive?, session-surflet-name
+ . access to options: options-session-lifetime,
+ options-cache-surflets?
+** structures: (3) surflet-handler/primitives
+ provides: . Access to the primitives of the
+ surflet handler:
+ . send/suspend, ... that send surflet responses
+ . send-error (sending Webserver error message)
+ . make-surflet-response, ... status-code:
+ surflet responses with own status-code, own
+ content-type, own headers and own content
+ (string or list of strings)
+ . surflet-requests...
+
+
+* (c) Administrative User
+** structures: (1) surflet-handler/admin
+ provides: . Access to all internal structures of the
+ handler
+ . surflets: get-loaded-surflets, unload-surflet
+ . sessions: get-session, get-sessions,
+ session-data, instance-session-id,
+ adjust-timeout..., session-record selectors
+ . continuations: get-continuations,
+ delete-continuations!
+ . resume-urls: resume-url?, resume-url-ids...
+ . options: options-session-lifetime...
+ set-options...!
+ surflet-handler/admin is splitted in several
+ parts, that can be loaded independently from
+ each other.
+
+** structures: (2) profiling
+ provides: . Access to memory usage of the whole scsh session
+ . profile-space, profile-results,
+ with-gnuplot-data-file, space-info-pair,
+ space-info-symbol...
+
+
+* (d) Various
+** structures: (1) surflets/outdaters
+ provides: . Data structure to prevent call for outdated
+ links. This is useful if in some places of your
+ session the user should not go back and recall
+ another continuation.
+ . make-outdater, if-outdated, show-outdated
+
+** structures: (2) surflets/utilities
+ provides: . Various utilities that didn't fit in another
+ package but were too small for an own one.
+ . form-query-list: url-query->alist
+ . rev-append
+ . make-callback enables you to place a callback
+ below a link. If the user clicks the link, an
+ arbitrary function is called.
+ . generate-unique-name generates name from a
+ prefix that are highest probable unique with
+ this prefix. For example this is used to
+ generate the names of the input fields.
+
+
+* HOWTO use your own conversion rules:
+
+** (i) Create your own conversion rules:
+
+ (trigger [*preorder*] . function)
+
+ - TRIGGER is the symbol that trigger the rule
+
+ - FUNCTION will get the trigger and the rest of the list, that
+ triggered the rule as arguments. Thus, if you know, you will
+ only get (at least x) arguments, FUNCTION must accept (at
+ least) x+1 arguments. FUNCTION must return a list
+ containing only characters or strings or, recursively, lists
+ of this type. (Well, there may be others also, but this is
+ too advanced.)
+
+ - If *PREORDER* misses, the rules will be first applied to all
+ arguments, before the are passed to function.
+
+
+*** Examples:
+ MY-HEAD will take no args and creates my heading:
+
+ (define my-head-rule
+ `(my-head . (lambda (trigger)
+ (list "My Page"
+ title
+ "STRING/INTERNAL
+ MY-ATTRIBUTED-HEAD takes attributes as well. As we don't want
+ to reformat this on our own, we use SXML->STRING/INTERNAL,
+ assuming that MY-RULES contains *all* the rules we use for
+ this sublist. As we do everything for the rest of the tree
+ ourselves, we use *preorder*:
+ (define my-attributed-head
+ `(my-attributed-head *preorder* .
+ ,(lambda (trigger attributes title)
+ (sxml->string/internal `(head ,attributes (title ,title))
+ my-rules))))
+
+** (ii) Create your own rule set.
+ A rule set is a list of conversion rules.
+
+*** Example:
+ (define my-rules
+ (list default-rule
+ attribute-rule
+ text-rule
+ my-head-rule
+ my-title-head
+ my-attributed-head))
+
+*** Note:
+ If you want to use SXML->STRING/INTERNAL with the same
+ rule set that entered the rule, you have to define them
+ either on top level with define or with letrec like
+
+ (letrec ((my-rules
+ (cons my-attributed-head-rule default-rules))
+ (my-attributed-head-rule
+ `(my-attributed-head *preorder* .
+ ,(lambda (trigger attributes title)
+ (sxml->string/internal `(head ,attributes (title ,title))
+ my-rules)))))
+ my-rules)
+
diff --git a/scheme/httpd/surflets/web-server/root/surflets/add-html.scm b/scheme/httpd/surflets/web-server/root/surflets/add-html.scm
index a0fd046..fe5353c 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/add-html.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/add-html.scm
@@ -2,6 +2,7 @@
(open surflets
surflets/utilities ;form-query-list
surflet-requests
+ surflet-handler/primitives
httpd-responses
url
scheme-with-scsh)
diff --git a/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm b/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm
index e98f2ba..c5d30d3 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm
@@ -5,7 +5,7 @@
url ; HTTP-url-SEARCH
srfi-1 ; FILTER
surflet-handler/surflets ; SEND/SUSPEND, SEND/FINISH
- surflet-handler/responses ; MAKE-SURFLET-RESPONSE
+ surflet-handler/primitives ; MAKE-SURFLET-RESPONSE
scheme-with-scsh)
(begin
diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm
index c8cab58..905979b 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm
@@ -3,8 +3,8 @@
handle-fatal-error
let-opt
surflets
- surflet-handler/admin
- httpd-responses
+ surflets/error
+ surflet-handler/options
)
(begin
diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm
index 2a0f2a5..0563f23 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm
@@ -1,17 +1,16 @@
(define-structure surflet surflet-interface
(open scheme-with-scsh
surflets
- surflet-handler/admin
+ surflets/sessions
+ surflets/error
profiling
handle-fatal-error
- httpd-responses
(subset srfi-1 (iota))
define-record-types
locks
let-opt
receiving
- primitives
- handle-fatal-error
+ (subset primitives (add-finalizer!))
)
(begin
diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm
index 5bab20f..968a5d4 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm
@@ -3,8 +3,8 @@
surflets
surflets/utilities ;make-callback
surflets/outdaters
+ surflets/error
surflet-handler/admin
- httpd-responses
handle-fatal-error
let-opt
srfi-1 ;filter-map
diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm
index 18fbe7c..69285be 100644
--- a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm
+++ b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm
@@ -4,10 +4,8 @@
surflets/utilities ;make-callback
surflets/outdaters
surflets/ids
+ surflets/error
surflet-handler/admin
- httpd-responses
- surflet-requests
- url
handle-fatal-error
let-opt
srfi-1 ;filter-map, last