Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Squatting(3)	      User Contributed Perl Documentation	  Squatting(3)

NAME
       Squatting - A Camping-inspired Web Microframework for Perl

SYNOPSIS
       Running an App:

	 $ squatting App
	 Please	contact	me at: http://localhost:4234/

       Check out our ASCII art logo:

	 $ squatting --logo

       What a basic App	looks like:

	 # STEP	1 => Use Squatting for your App
	 {
	   package App;	 # <-- I hope it's obvious that	this name can whatever you want.
	   use Squatting;
	   our %CONFIG;	 # <-- standard	app config goes	here
	 }

	 # STEP	2 => Define the	App's Controllers
	 {
	   package App::Controllers;

	   # Setup a list of controller	objects	in @C using the	C() function.
	   our @C = (
	     C(
	       Home => [ '/' ],
	       get  => sub {
		 my ($self) = @_;
		 my $v = $self->v;
		 $v->{title}   = 'A Simple Squatting Application';
		 $v->{message} = 'Hello, World!';
		 $self->render('home');
	       },
	       post => sub { }
	     ),
	   );
	 }

	 # STEP	3 => Define the	App's Views
	 {
	   package App::Views;

	   # Setup a list of view objects in @V	using the V() function.
	   our @V = (
	     V(
	       'html',
	       layout  => sub {
		 my ($self, $v,	$content) = @_;
		 "<html><head><title>$v->{title}</title></head>".
		 "<body>$content</body></html>";
	       },
	       home    => sub {
		 my ($self, $v)	= @_;
		 "<h1>$v->{message}</h1>"
	       },
	     ),
	   );
	 }

	 # Models?
	 # - The whole world is	your model.  ;-)
	 # - I have no interest	in defining policy here.
	 # - Use whatever works	for you.

DESCRIPTION
       Squatting is a web microframework based on Camping.  It originally used
       Continuity as its foundation, but it has	since been generalized such
       that it can squat on top	of any Perl-based web framework	(in theory).

   What	does this mean?
       Concise API
	   _why	did a really good job designing	Camping's API so that you
	   could get the MOST done with	the LEAST amount of code possible.  I
	   loved Camping's API so much that I ported it	to Perl.

       Tiny Codebase
	   The core of Squatting (which	includes Squatting,
	   Squatting::Controller, and Squatting::View) can be squished into
	   less	than 4K	of obfuscated perl.  Also, the number of Perl module
	   dependencies	has been kept down to a	minimum.

       RESTful Controllers By Default
	   Controllers are objects (not	classes) that are made to look like
	   HTTP	resources.  Thus, they respond to methods like get(), post(),
	   put(), and delete().

       RESTless	Controllers Are	Possible
	   Stateful continuation-based code can	be surprisingly	useful
	   (especially for COMET), so we try to	make RESTless controllers easy
	   to express as well. (*)

       Squatting Apps Can Have Multiple	Views
	   Views are also objects (not classes)	whose methods represent
	   templates to	be rendered.  An app can also have more	than one view.
	   Changing a Squatting	app's look and feel can	be as simple as
	   swapping out	one view object	for another.

       Squatting Apps Are Composable
	   You can take	multiple Squatting apps	and compose them into a	single
	   app.	 For example, suppose you built	a site and decided that	you'd
	   like	to add a forum.	 You could take	a hypothetical forum app
	   written in Squatting	and just mount it at an	arbitrary path like
	   /forum.

       Squatting Apps Are Embeddable
	   Already using another framework?  No	problem.  You should be	able
	   to embed Squatting apps into	apps written in	anything from CGI on
	   up to Catalyst.  Squatting aims to be compatible with EVERYONE.

       Minimal Policy
	   You may use any templating system you want, and you may use any ORM
	   you want.  We only have a few rules on how the controller code and
	   the view code should	be organized, but beyond that, you are free as
	   you want to be.

       * RESTless controllers currently	only work when you're
       Squatting::On::Continuity.

API
   Use as a Base Class for Squatting Applications
	 package App;
	 use Squatting;
	 our %CONFIG = ();
	 1;

       Just "use"ing Squatting makes a lot of magic happen.  In	the example
       above:

       App becomes a subclass of Squatting.
       App::Controllers	is given this app's R()	and C()	functions.
       App::Views is given this	app's R() and V() functions.

       App-_service($controller, @args)

       Every time an HTTP request comes	in, this method	is called with a
       controller object and a list of arguments.  The controller will then be
       invoked with the	HTTP method that was requested (like GET or POST), and
       it will return the content of the response as a string.

       NOTE:  If you want to do	anything before, after,	or around an HTTP
       request,	this is	the method you should override in your subclass.

       App-_init

       This method takes no parameters and initializes some internal
       variables.

       NOTE:  You can override this method if you want to do more things when
       the App is initialized.

       App-_mount($AnotherApp =_ $prefix)

       XXX - The "mount()" has been moved out of the core and into
       Squatting::With::Mount.	Furthermore, Squatting::With::Mount has	been
       implemented using Squatting::On::Squatting.

       This method will	mount another Squatting	app at the specified prefix.

	 App->mount('My::Blog'	 => '/my/ridiculous/rantings');
	 App->mount('Forum'	 => '/forum');
	 App->mount('ChatterBox' => '/chat');

       NOTE:  You can only mount an app	once.  Don't try to mount it again at
       some other prefix, because it won't work.  This is a consequence	of
       storing so much information in package variables	and a strong argument
       for going all objects all the time.

       App-_relocate($prefix)

       This method will	relocate a Squatting app to the	specified prefix.
       It's useful for embedding a Squatting app into apps written in other
       frameworks.

       This also has a side-effect of setting $CONFIG{relocated} to $prefix.

   Use as a Helper for Controllers
       In this package,	you will define	a list of Squatting::Controller
       objects in @C.

	 package App::Controllers;
	 use Squatting ':controllers';
	 our @C	= (
	   C(...),
	   C(...),
	   C(...),
	 );

       C($name =_ \@urls, %methods)

       This is a shortcut for:

	 Squatting::Controller->new(
	   $name => \@urls,
	   app	 => $App,
	   %methods
	 );

       R($name,	@args, [ \%params ])

       R() is a	URL generation function	that takes a controller	name and a
       list of arguments.  You may also	pass in	a hashref representing CGI
       variables as the	very last parameter to this function.

       Example:	 Given the following controllers, R() would respond like this.

	 # Example Controllers
	 C(Home	   => [	'/' ]);
	 C(Profile => [	'/~(\w+)', '/~(\w+)\.(\w+)' ]);

	 # Generated URLs
	 R('Home')			       # "/"
	 R('Home', { foo => 1, bar => 2})      # "/?foo=1&bar=2"
	 R('Profile', 'larry')		       # "/~larry"
	 R('Profile', 'larry', 'json')	       # "/~larry.json"

       As you can see, @args represents	the regexp captures, and "\%params"
       represents the CGI query	parameters.

   Use as a Helper for Views
       In this package,	you will define	a list of Squatting::View objects in
       @V.

	 package App::Views;
	 use Squatting ':views';
	 our @V	= (
	   V(
	     'html',
	     home => sub { "<h1>Home</h1>" },
	   ),
	 );

       V($name,	%methods)

       This is a shortcut for:

	 Squatting::View->new($name, %methods);

       R($name,	@args, [ \%params ])

       This is the same	R() function that the controllers get access to.
       Please use it to	generate URLs so that your apps	may be composable and
       embeddable.

SEE ALSO
       Other Squatting::* modules:
	   Squatting::Controller, Squatting::View, Squatting::Mapper,
	   Squatting::H, Squatting::On::Continuity, Squatting::On::Catalyst,
	   Squatting::On::CGI, Squatting::On::MP13, Squatting::On::MP20,
	   Squatting::With::AccessTrace, Squatting::With::Log,
	   Squatting::With::Coro::Debug

	   Squatting::On::PSGI,	Squatting::On::Mojo,
	   Squatting::On::HTTP::Engine

       Squatting's superclass:
	   Class::C3::Componentised

       Squatting apps you can find on CPAN:
	   Pod::Server - a nice	way to browse through the POD for your locally
	   installed perl modules.

	   Stardust - a	simple COMET server.  (DEPRECATED.  Use	Web::Hippie or
	   Plack::Middleware::SocketIO instead.)

	   Rhetoric - a	simple CPAN-friendly blogging system for Perl.

   Google Group:  squatting-framework
       A Google	Group has been setup so	that people can	discuss	Squatting.  If
       you have	questions about	the framework, this is the place to ask.

       <http://groups.google.com/group/squatting-framework>

   Squatting Source Code
       The source code is short	and it has some	useful comments	in it, so this
       might be	all you	need to	get going.  There are also some	examples in
       the eg/ directory.

       <http://github.com/beppu/squatting/tree/master>

   Bavl	Source Code
       We're going to throw Squatting (and Continuity) into the	metaphorical
       deep end	by using it to implement the <http://towr.of.bavl.org/>.  It's
       a site that will	help people learn foreign languages by letting you
       hear the	phrases	you're interested in learning as actually spoken by
       fluent speakers.	 If you're looking for an example of how to use
       Squatting for an	ambitious project, look	at the Bavl code.

       <http://github.com/beppu/bavl/tree/master>

   Continuity and Coro
       When you	want to	start dabbling with RESTless controllers, it would
       serve you well to understand how	Continuity, Coro and Event work.  To
       learn more, I recommend reading the POD for the following Perl modules:

       Continuity, Coro, AnyEvent.

       Combining coroutines with an event loop is a surprisingly powerful
       technique.

   Camping
       Squatting is descended from Camping, so studying	the Camping API	will
       indirectly teach	you much of the	Squatting API.

       <http://github.com/why/camping/tree/master>

   Prototype-based OO
       There were a lot	of obscure Ruby	idioms in Camping that were damn near
       impossible to directly translate	into Perl.  I got around this by
       resorting to techniques that are	reminiscent of prototype-based OO.
       (That's why controllers and views are objects instead of	classes.)

       Prototypes == Grand Unified Theory of Objects

       I've been coding	a lot of JavaScript these days,	and it has definitely
       influenced my programming style.	 I've come to love the simplicity of
       prototype-based OO, and I think it's a damned shame that	they're
       introducing concepts like 'class' in the	next version of	JavaScript.
       It's like they missed the point of prototype-based OO.

       If you're going to add anything to JavaScript, make the prototype side
       of it stronger.	Look to	languages like Io, and make it easier to clone
       objects and manipulate an object's prototype chain.  The	beauty of
       prototypes is that you can combine it with slot-based objects to	unify
       the functionality of objects, classes, and namespaces into a
       surprisingly simple and coherent	system.	 Look at Io if you don't
       believe me.

       <http://iolanguage.com/>

AUTHOR
       John BEPPU <beppu@cpan.org>

       Scott WALTERS (aka scrottie) gets credit	for the	name of	this module.

COPYRIGHT
       Copyright (c) 2008-9 John BEPPU <beppu@cpan.org>.

   The "MIT" License
       Permission is hereby granted, free of charge, to	any person obtaining a
       copy of this software and associated documentation files	(the
       "Software"), to deal in the Software without restriction, including
       without limitation the rights to	use, copy, modify, merge, publish,
       distribute, sublicense, and/or sell copies of the Software, and to
       permit persons to whom the Software is furnished	to do so, subject to
       the following conditions:

       The above copyright notice and this permission notice shall be included
       in all copies or	substantial portions of	the Software.

       THE SOFTWARE IS PROVIDED	"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
       OR IMPLIED, INCLUDING BUT NOT LIMITED TO	THE WARRANTIES OF
       MERCHANTABILITY,	FITNESS	FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
       IN NO EVENT SHALL THE AUTHORS OR	COPYRIGHT HOLDERS BE LIABLE FOR	ANY
       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN	ACTION OF CONTRACT,
       TORT OR OTHERWISE, ARISING FROM,	OUT OF OR IN CONNECTION	WITH THE
       SOFTWARE	OR THE USE OR OTHER DEALINGS IN	THE SOFTWARE.

perl v5.32.1			  2014-02-20			  Squatting(3)

NAME | SYNOPSIS | DESCRIPTION | API | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Squatting&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help