summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2017-12-16 17:15:08 +0100
committerYorhel <git@yorhel.nl>2017-12-16 17:15:11 +0100
commit24529acdb4aca29e47ae5c0decfec337da79d4b5 (patch)
tree773727b475fc328174a3a5f95b7a4ba2147b1c17
parentd77958674603a09c1d8a702dbbe876e10e2c51b6 (diff)
Documentation fixes and updates
I removed the part about backward compatibility. Not that I will now fully guarantee that there won't be any breaking changes, but there's a bit too much TUWF-using code around that breaking major stuff is only going to cause me a lot of work.
-rw-r--r--lib/TUWF.pod52
-rw-r--r--lib/TUWF/DB.pod20
-rw-r--r--lib/TUWF/Request.pod12
-rw-r--r--lib/TUWF/Response.pod26
4 files changed, 46 insertions, 64 deletions
diff --git a/lib/TUWF.pod b/lib/TUWF.pod
index fb0ccd9..4b733b3 100644
--- a/lib/TUWF.pod
+++ b/lib/TUWF.pod
@@ -70,7 +70,7 @@ encoding before passing it to any TUWF function.
=item Designed for FastCGI environments.
TUWF is designed and optimized to be run a FastCGI environment, but it can also
-be used for plain old CGI scripts and it can run as a standalone HTTP server.
+be used for plain old CGI scripts or run as a standalone HTTP server.
Due to the singleton design of TUWF, you should avoid running TUWF websites in
persistent environments that allow multiple websites to share the same process,
@@ -107,20 +107,6 @@ subdomains in the same TUWF script. A common solution is to write a separate
script for each subdomain. It is still possible to share code among both sites
by means of modules.
-=item Backward compatibility is not guaranteed.
-
-TUWF is the result of years of evolution, from one implementation to another
-and from one design to another. The reason TUWF has become what it is now is
-because of this unconstrained evolution. Providing backward compatibility in
-many cases complicates the implementation of new ideas and may add unwanted
-bloat to the framework. For this reason, future versions of TUWF may work
-differently from older versions, and may not be backward compatible with code
-written for an older version.
-
-When using TUWF for your project, it is adviced to get one version of TUWF and
-stick to that, until you have time to check out a later version and update your
-code to work with that one.
-
=back
@@ -136,10 +122,10 @@ the website is spread among the various modules.
The script can load the modules by calling C<TUWF::load()> or
C<TUWF::load_recursive()>. TUWF configuration variables can be set using
-C<TUWF::set()>, and URIs can be mapped to functions using C<TUWF::register()>.
-These functions can also be called by the loaded modules. In fact, for larger
-websites it is common for the script to only initialize TUWF and load the
-modules, while all calls to C<TUWF::register()> are done from the modules.
+C<TUWF::set()>, and routing handlers can be registered through C<TUWF::get()>
+and friends. These functions can also be called by the loaded modules. In
+fact, for larger websites it is common for the script to only initialize TUWF
+and load the modules, while routing handlers are registered in the modules.
The framework is based on callbacks: At initialization, your code registers
callbacks to the framework and then passes the control to TUWF using
@@ -150,11 +136,11 @@ functions you registered.
=head2 The TUWF Object
While TUWF can not really be called I<object oriented>, it does use B<one>
-major object, called the I<TUWF object>. This object can be accessed from
-C<$TUWF::OBJ> and is passed as the first argument to all callback functions.
-Even though it is an "instance" of C<TUWF::Object>, you are encouraged to use
-it as if it is the main object for your website: You can use it to store global
-configuration settings and other shared data.
+major object, called the I<TUWF object>. This object can be accessed using the
+C<tuwf()> function that is exported by default, or by accessing C<$TUWF::OBJ>
+directly. Even though it is an "instance" of C<TUWF::Object>, you are
+encouraged to use it as if it is the main object for your website: You can use
+it to store global configuration settings and other shared data.
All modules loaded using C<TUWF::load()> and its recursive counterpart can
export functions; These functions are automatically imported in the
@@ -177,7 +163,7 @@ or standalone mode. In particular, it is a bad idea to store session data in
this object, assuming it to be available on the next request. Storing data
specific to a single request in the object is fine, as long as you make sure to
reset or re-initialize the data at the beginning of the request. The
-C<pre_request_handler> is useful for such practice.
+I<before> hook is useful for such practice.
=head2 Utility functions
@@ -401,10 +387,10 @@ individual call to C<resCookie()>. This can be useful when globally setting the
cookie domain:
TUWF::set(cookie_defaults => { domain => '.example.org' });
- $self->resCookie(foo => 'bar');
+ tuwf->resCookie(foo => 'bar');
# is equivalent to:
- $self->resCookie(foo => 'bar', domain => '.example.org');
+ tuwf->resCookie(foo => 'bar', domain => '.example.org');
# for each call to resCookie()
Default: undef (disabled).
@@ -622,18 +608,16 @@ for the methods it provides.
Returns the capture group from the route regex. Both positional captures and
named captures can be used, for example:
- TUWF::register(qr{user/(?<uid>[1-9][0-9]*)} => sub {
- my($self, $uid) = @_;
-
+ TUWF::get qr{/user/(?<uid>[1-9][0-9]*)} => sub {
# capture(1) is equivalent to $1 from the regex.
- $self->capture(1) == $uid;
+ tuwf->capture(1) == $uid;
# capture('uid') is equivalent to $+{uid} from the regex.
- $self->capture('uid') == $uid;
- });
+ tuwf->capture('uid') == $uid;
+ };
Note that C<captures(0)> is not available; This would be equivalent to
-C<< $self->reqPath >>, save for the leading slash.
+C<< tuwf->reqPath >>, save for the leading slash.
=head2 debug()
diff --git a/lib/TUWF/DB.pod b/lib/TUWF/DB.pod
index 34157cc..0c6bde5 100644
--- a/lib/TUWF/DB.pod
+++ b/lib/TUWF/DB.pod
@@ -45,9 +45,9 @@ most likely work as well, but you might run into some issues.
=head2 Every request is one transaction
TUWF automatically makes sure that before a request will be processed (that is,
-before the I<pre_request_handler> is called), the database connection will be
-in a clean state and has just started a new transaction. After the request has
-been successfully handled (that is, none of your functions C<die()>'d), the
+before the I<before> hooks are called), the database connection will be in a
+clean state and has just started a new transaction. After the request has been
+successfully handled (that is, none of your functions C<die()>'d), the
transaction will be committed automatically. If something went wrong while
processing the request, the transaction will be rolled back before the
I<error_500_handler> is called. So from the perspective of the database, each
@@ -87,11 +87,11 @@ extended formatting codes in the query.
Example of an "UPDATE or INSERT" query:
- $self->dbExec(
+ tuwf->dbExec(
'UPDATE users !H !W',
{'username = ?' => $user, 'email = ?' => $email},
{'id = ?' => $uid}
- ) || $self->dbExec(
+ ) || tuwf->dbExec(
'INSERT INTO users (id, username, email) VALUES(!l)',
[ $uid, $user, $email ]
);
@@ -108,14 +108,14 @@ query did not return any rows.
Examples:
- my $count = $self->dbRow('SELECT COUNT(*) AS num FROM users')->{num};
+ my $count = tuwf->dbRow('SELECT COUNT(*) AS num FROM users')->{num};
- my %latest_announcement = %{$self->dbRow(q{
+ my %latest_announcement = %{ tuwf->dbRow(q{
SELECT title, message, post_date
FROM announcements
ORDER BY post_date DESC
LIMIT 1
- })};
+ }) };
die "No announcements!" if !keys %latest_announcement;
=head2 dbAll(query, @params)
@@ -138,12 +138,12 @@ is either 0 or 1, and indicates whether there are more rows. That is, if the
second value is true, calling the this method with the same arguments but with
the I<page> option increased with one will return at least one more row.
- my($rows, $nextpage) = $self->dbPage(
+ my($rows, $nextpage) = tuwf->dbPage(
{page => 2, results => 10},
'SELECT title FROM threads ORDER BY title'
);
# $rows is now equivalent to:
- # $self->dbAll('SELECT title FROM threads ORDER BY title LIMIT 10 OFFSET 10')
+ # tuwf->dbAll('SELECT title FROM threads ORDER BY title LIMIT 10 OFFSET 10')
The value of C<$nextpage> is determined by fetching one row more than requested
and later removing it from the results.
diff --git a/lib/TUWF/Request.pod b/lib/TUWF/Request.pod
index fb6f18a..be6774f 100644
--- a/lib/TUWF/Request.pod
+++ b/lib/TUWF/Request.pod
@@ -28,9 +28,9 @@ Examples:
# Let the query string be the following:
# "key=value&foo=bar1&foo=bar2"
# Then:
- my @list = $self->reqGets(); # @list = ('key', 'foo')
- my @foo = $self->reqGets('foo'); # @foo = ('bar1', 'bar2')
- my @no = $self->reqGets('no'); # @no = ()
+ my @list = tuwf->reqGets(); # @list = ('key', 'foo')
+ my @foo = tuwf->reqGets('foo'); # @foo = ('bar1', 'bar2')
+ my @no = tuwf->reqGets('no'); # @no = ()
=head2 reqGet(name)
@@ -39,7 +39,7 @@ C<(reqGets($name))[0]>. The name argument is required. Since this method only
ever returns a scalar value, it is safe to use when constructing lists:
my %stuff = (
- name => $self->reqGet('name'),
+ name => tuwf->reqGet('name'),
);
Don't do that with C<reqGets()>, as it may leave you vulnerable to parameter
@@ -142,10 +142,10 @@ For example:
TUWF::set(cookie_prefix => 'ex_');
# ...later, when processing a request,
- my $auth = $self->reqCookie('auth'); # actually means 'ex_auth'
+ my $auth = tuwf->reqCookie('auth'); # actually means 'ex_auth'
# when assuming the 'ex_auth' cookie to be present,
- my @cookies = $self->reqCookie(); # @cookies = ('auth')
+ my @cookies = tuwf->reqCookie(); # @cookies = ('auth')
=head2 reqMethod()
diff --git a/lib/TUWF/Response.pod b/lib/TUWF/Response.pod
index a7db551..55bf14d 100644
--- a/lib/TUWF/Response.pod
+++ b/lib/TUWF/Response.pod
@@ -20,12 +20,12 @@ be reset to their defaults. This method is called at the start of each request
by TUWF, but it can also be useful in your own code:
# create a response, setting headers and content, etc...
- $self->resCookie(userid => $user);
- print { $self->resFd() } "Content!\n";
+ tuwf->resCookie(userid => $user);
+ print { tuwf->resFd() } "Content!\n";
# when you later decide that you actually wanted to create a totally
# different response:
- $self->resInit();
+ tuwf->resInit();
# ...after which you can start again
=head2 resHeader(name, value, add)
@@ -188,8 +188,8 @@ written to the buffer. This method also disables output compression to prevent
additional copies of the data. Make sure to set the right content type as well,
for example:
- $self->resHeader('Content-Type' => 'image/jpeg');
- $self->resBinary($image_data);
+ tuwf->resHeader('Content-Type' => 'image/jpeg');
+ tuwf->resBinary($image_data);
=head2 resFile(path, filename)
@@ -206,23 +206,21 @@ calling C<resHeader()> after C<resFile()>.
Examples:
# Serve 'GET /static/x' requests from /webroot/public
- TUWF::register(qr{static/(.+)} => sub {
- my($self, $fn) = @_;
- $self->resFile('/webroot/public', $fn) || $self->resNotFound;
- });
+ TUWF::get qr{/static/(.+)} => sub {
+ tuwf->resFile('/webroot/public', tuwf->captures(1)) || tuwf->resNotFound;
+ };
# Serve a file in '/webroot/public' if it exists,
# otherwise handle the request as usual.
- TUWF::set(pre_request_handler => sub {
- my $self = shift;
- return 0 if $self->resFile('/webroot/public', $self->reqPath);
+ TUWF::hook before => sub {
+ return 0 if tuwf->resFile('/webroot/public', tuwf->reqPath);
return 1;
- });
+ };
You might also want to set proper caching headers if the static files don't
change much:
- $self->resHeader('Cache-Control' => 'max-age=31536000');
+ tuwf->resHeader('Cache-Control' => 'max-age=31536000');
C<resFile()> uses C<resBinary()> internally, so output compression will be
disabled for these files. Furthermore, this method is not really suitable for