diff options
author | Yorhel <git@yorhel.nl> | 2017-12-16 17:15:08 +0100 |
---|---|---|
committer | Yorhel <git@yorhel.nl> | 2017-12-16 17:15:11 +0100 |
commit | 24529acdb4aca29e47ae5c0decfec337da79d4b5 (patch) | |
tree | 773727b475fc328174a3a5f95b7a4ba2147b1c17 | |
parent | d77958674603a09c1d8a702dbbe876e10e2c51b6 (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.pod | 52 | ||||
-rw-r--r-- | lib/TUWF/DB.pod | 20 | ||||
-rw-r--r-- | lib/TUWF/Request.pod | 12 | ||||
-rw-r--r-- | lib/TUWF/Response.pod | 26 |
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 |