From 615c380015c5afe512788ce21c08bbcf350fd1a7 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Fri, 14 Nov 2008 04:01:26 -0600 Subject: [PATCH] Working on docs for furnace.json, furnace.redirection, and furnace.referrer --- .../boilerplate/boilerplate-docs.factor | 27 +++ basis/furnace/furnace-docs.factor | 189 ++++++++++++++++++ basis/furnace/furnace.factor | 23 +++ basis/furnace/json/json-docs.factor | 2 +- .../redirection/redirection-docs.factor | 58 ++++++ basis/furnace/referrer/referrer-docs.factor | 15 ++ .../syndication/syndication-docs.factor | 69 +++++++ 7 files changed, 382 insertions(+), 1 deletion(-) create mode 100644 basis/furnace/boilerplate/boilerplate-docs.factor create mode 100644 basis/furnace/furnace-docs.factor create mode 100644 basis/furnace/redirection/redirection-docs.factor create mode 100644 basis/furnace/referrer/referrer-docs.factor create mode 100644 basis/furnace/syndication/syndication-docs.factor diff --git a/basis/furnace/boilerplate/boilerplate-docs.factor b/basis/furnace/boilerplate/boilerplate-docs.factor new file mode 100644 index 0000000000..5594928082 --- /dev/null +++ b/basis/furnace/boilerplate/boilerplate-docs.factor @@ -0,0 +1,27 @@ +! Copyright (C) 2008 Your name. +! See http://factorcode.org/license.txt for BSD license. +USING: help.markup help.syntax io.streams.string ; +IN: furnace.boilerplate + +HELP: +{ $values + { "responder" null } + { "boilerplate" null } +} +{ $description "" } ; + +HELP: boilerplate +{ $description "" } ; + +HELP: wrap-boilerplate? +{ $values + { "response" null } + { "?" "a boolean" } +} +{ $description "" } ; + +ARTICLE: "furnace.boilerplate" "Furnace boilerplate support" +{ $vocab-link "furnace.boilerplate" } +; + +ABOUT: "furnace.boilerplate" diff --git a/basis/furnace/furnace-docs.factor b/basis/furnace/furnace-docs.factor new file mode 100644 index 0000000000..0e2e6c1f40 --- /dev/null +++ b/basis/furnace/furnace-docs.factor @@ -0,0 +1,189 @@ +USING: assocs help.markup help.syntax io.streams.string quotations sequences strings urls ; +IN: furnace + +HELP: adjust-redirect-url +{ $values + { "url" url } + { "url'" url } +} +{ $description "" } ; + +HELP: adjust-url +{ $values + { "url" url } + { "url'" url } +} +{ $description "" } ; + +HELP: base-path +{ $values + { "string" string } + { "pair" null } +} +{ $description "" } ; + +HELP: client-state +{ $values + { "key" null } + { "value/f" null } +} +{ $description "" } ; + +HELP: cookie-client-state +{ $values + { "key" null } { "request" null } + { "value/f" null } +} +{ $description "" } ; + +HELP: each-responder +{ $values + { "quot" quotation } +} +{ $description "" } ; + +HELP: exit-continuation +{ $description "" } ; + +HELP: exit-with +{ $values + { "value" null } +} +{ $description "" } ; + +HELP: hidden-form-field +{ $values + { "value" null } { "name" null } +} +{ $description "" } ; + +HELP: link-attr +{ $values + { "tag" null } { "responder" null } +} +{ $description "" } ; + +HELP: modify-form +{ $values + { "responder" null } +} +{ $description "" } ; + +HELP: modify-query +{ $values + { "query" null } { "responder" null } + { "query'" null } +} +{ $description "" } ; + +HELP: modify-redirect-query +{ $values + { "query" null } { "responder" null } + { "query'" null } +} +{ $description "" } ; + +HELP: nested-forms-key +{ $description "" } ; + +HELP: nested-responders +{ $values + + { "seq" sequence } +} +{ $description "" } ; + +HELP: post-client-state +{ $values + { "key" null } { "request" null } + { "value/f" null } +} +{ $description "" } ; + +HELP: referrer +{ $values + + { "referrer/f" null } +} +{ $description "" } ; + +HELP: request-params +{ $values + { "request" null } + { "assoc" assoc } +} +{ $description "" } ; + +HELP: resolve-base-path +{ $values + { "string" string } + { "string'" string } +} +{ $description "" } ; + +HELP: resolve-template-path +{ $values + { "pair" null } + { "path" "a pathname string" } +} +{ $description "" } ; + +HELP: same-host? +{ $values + { "url" url } + { "?" "a boolean" } +} +{ $description "" } ; + +HELP: user-agent +{ $values + + { "user-agent" null } +} +{ $description "" } ; + +HELP: vocab-path +{ $values + { "vocab" "a vocabulary specifier" } + { "path" "a pathname string" } +} +{ $description "" } ; + +HELP: with-exit-continuation +{ $values + { "quot" quotation } +} +{ $description "" } ; + +ARTICLE: "furnace" "Furnace web framework" +"The " { $vocab-link "furnace" } " vocabulary implements a full-featured web framework on top of the " { $link "http.server" } ". Some of its features include:" +{ $list + "Session management capable of load-balancing and fail-over" + "Form components and validation" + "Authentication system with basic authentication or login pages, and pluggable authentication backends" + "Easy Atom feed syndication" + "Conversation scope and asides for complex page flow" +} +"Major functionality:" +{ $subsection "furnace.actions" } +{ $subsection "furnace.syndication" } +{ $subsection "furnace.boilerplate" } +{ $subsection "furnace.db" } +"Server-side state:" +{ $subsection "furnace.sessions" } +{ $subsection "furnace.conversations" } +{ $subsection "furnace.asides" } +"HTML components:" +{ $subsection "html.components" } +{ $subsection "html.forms" } +"Content templates:" +{ $subsection "html.templates" } +{ $subsection "html.templates.chloe" } +{ $subsection "html.templates.fhtml" } +"Utilities:" +{ $subsection "furnace.alloy" } +{ $subsection "furnace.json" } +{ $subsection "furnace.redirection" } +{ $subsection "furnace.referrer" } ; + +ABOUT: "furnace" diff --git a/basis/furnace/furnace.factor b/basis/furnace/furnace.factor index 7285c436bc..a77b0d28c7 100644 --- a/basis/furnace/furnace.factor +++ b/basis/furnace/furnace.factor @@ -128,4 +128,27 @@ SYMBOL: exit-continuation : with-exit-continuation ( quot -- ) '[ exit-continuation set @ ] callcc1 exit-continuation off ; +USE: vocabs.loader +"furnace.actions" require +"furnace.alloy" require +"furnace.asides" require +"furnace.auth" require +"furnace.auth.basic" require +"furnace.auth.features.deactivate-user" require +"furnace.auth.features.edit-profile" require +"furnace.auth.features.recover-password" require +"furnace.auth.features.registration" require +"furnace.auth.login" require +"furnace.auth.providers.assoc" require +"furnace.auth.providers.db" require +"furnace.auth.providers.null" require +"furnace.boilerplate" require "furnace.chloe-tags" require +"furnace.conversations" require +"furnace.db" require +"furnace.json" require +"furnace.redirection" require +"furnace.referrer" require +"furnace.scopes" require +"furnace.sessions" require +"furnace.syndication" require diff --git a/basis/furnace/json/json-docs.factor b/basis/furnace/json/json-docs.factor index daa84e9295..c20c2e6c91 100644 --- a/basis/furnace/json/json-docs.factor +++ b/basis/furnace/json/json-docs.factor @@ -1,4 +1,4 @@ -USING: kernel http.server help.markup help.syntax ; +USING: kernel http.server help.markup help.syntax http ; IN: furnace.json HELP: diff --git a/basis/furnace/redirection/redirection-docs.factor b/basis/furnace/redirection/redirection-docs.factor new file mode 100644 index 0000000000..42fd3a1f2a --- /dev/null +++ b/basis/furnace/redirection/redirection-docs.factor @@ -0,0 +1,58 @@ +USING: help.markup help.syntax io.streams.string quotations urls +http.server http ; +IN: furnace.redirection + +HELP: +{ $values { "url" url } { "responder" "a responder" } } +{ $description "Creates a responder which unconditionally redirects the client to the given URL." } ; + +HELP: +{ $values { "url" url } { "response" response } } +{ $description "Creates a response which redirects the client to the given URL." } ; + +HELP: ( responder -- responder' ) +{ $description "Creates a new responder which ensures that the client is connecting via HTTPS before delegating to the underlying responder. If the client is connecting via HTTP, a redirect is sent instead." } ; + +HELP: +{ $values + { "url" url } + { "response" response } +} +{ $description "Creates a responder which unconditionally redirects the client to the given URL after setting its protocol to HTTPS." } +{ $notes "This word is intended to be used with a relative URL. The client is redirected to the relative URL, but with HTTPS instead of HTTP." } ; + +HELP: >secure-url +{ $values + { "url" url } + { "url'" url } +} +{ $description "Sets the protocol of a URL to HTTPS." } ; + +HELP: if-secure +{ $values + { "quot" quotation } + { "response" response } +} +{ $description "Runs a quotation if the current request was made over HTTPS, otherwise returns a redirect to have the client request the current page again via HTTPS." } ; + +ARTICLE: "furnace.redirection.secure" "Secure redirection" +"The words in this section help with implementing sites which require SSL/TLS for additional security." +$nl +"Converting a HTTP URL into an HTTPS URL:" +{ $subsection >secure-url } +"Redirecting the client to an HTTPS URL:" +{ $subsection } +"Tools for writing responders which require SSL/TLS connections:" +{ $subsection if-secure } +{ $subsection } ; + +ARTICLE: "furnace.redirection" "Furnace redirection support" +"The " { $vocab-link "furnace.redirection" } " vocabulary builds additional functionality on top of " { $vocab-link "http.server.redirection" } ", and integrates with various Furnace features such as " { $link "furnace.asides" } " and " { $link "furnace.conversations" } "." +$nl +"A redirection response which takes asides and conversations into account:" +{ $subsection } +"A responder which unconditionally redirects the client to another URL:" +{ $subsection } +{ $subsection "furnace.redirection.secure" } ; + +ABOUT: "furnace.redirection" diff --git a/basis/furnace/referrer/referrer-docs.factor b/basis/furnace/referrer/referrer-docs.factor new file mode 100644 index 0000000000..5deebbe9a7 --- /dev/null +++ b/basis/furnace/referrer/referrer-docs.factor @@ -0,0 +1,15 @@ +USING: help.markup help.syntax io.streams.string ; +IN: furnace.referrer + +HELP: +{ $values + { "responder" "a responder" } + { "responder'" "a responder" } +} +{ $description "Wraps the responder in a filter responder which ensures that form submissions originate from a page on the same server. Any submissions which do not are sent back with a 403 error." } ; + +ARTICLE: "furnace.referrer" "Form submission referrer checking" +"The " { $vocab-link "furnace.referrer" } " implements a simple security measure which can be used to thwart cross-site scripting attacks." +{ $subsection } ; + +ABOUT: "furnace.referrer" diff --git a/basis/furnace/syndication/syndication-docs.factor b/basis/furnace/syndication/syndication-docs.factor new file mode 100644 index 0000000000..7a9ec57468 --- /dev/null +++ b/basis/furnace/syndication/syndication-docs.factor @@ -0,0 +1,69 @@ +! Copyright (C) 2008 Your name. +! See http://factorcode.org/license.txt for BSD license. +USING: help.markup help.syntax io.streams.string kernel sequences strings urls ; +IN: furnace.syndication + +HELP: +{ $values + + { "action" null } +} +{ $description "" } ; + +HELP: +{ $values + { "body" null } + { "response" null } +} +{ $description "" } ; + +HELP: >entry +{ $values + { "object" object } + { "entry" null } +} +{ $description "" } ; + +HELP: feed-action +{ $description "" } ; + +HELP: feed-entry-date +{ $values + { "object" object } + { "timestamp" null } +} +{ $description "" } ; + +HELP: feed-entry-description +{ $values + { "object" object } + { "description" null } +} +{ $description "" } ; + +HELP: feed-entry-title +{ $values + { "object" object } + { "string" string } +} +{ $description "" } ; + +HELP: feed-entry-url +{ $values + { "object" object } + { "url" url } +} +{ $description "" } ; + +HELP: process-entries +{ $values + { "seq" sequence } + { "seq'" sequence } +} +{ $description "" } ; + +ARTICLE: "furnace.syndication" "Furnace Atom syndication support" +{ $vocab-link "furnace.syndication" } +; + +ABOUT: "furnace.syndication"