DOCSEARCHbyAlgolia
Submit Docs

Snap Web Framework

repository·master·Indexed 43 days ago

https://github.com/snapframework/snap-core

A high-performance web development framework and server written in Haskell. The snap-core library provides the fundamental building blocks, including the Snap monad for writing web handlers, primitive HTTP types, and utilities for handling cookies, query parameters, file serving, and compression.

Tokens
1.5K
Snippets
5
Records
10
Agent score
54%

What's inside Snap

  1. Overview of the Snap Framework core system

    master

    Snap is a high-performance web development framework and server written in Haskell. The core system is composed of four primary components:

    • A web programming monad: A sensible and clean monad designed specifically for web development tasks.
    • snap-server: A high-speed HTTP server.
    • heist: An XML-based templating system used for generating HTML. It allows binding Haskell functionality to XML tags to avoid 'tag soup'.
    • snaplet system: A system for building websites using composable pieces called 'snaplets'.

  2. What is the Snap monad?

    master

    The Snap monad is the core interface for programming web handlers in the Snap framework. It provides several key capabilities for web development:

    • Stateful HTTP Access: Provides stateful access to both the HTTP request and response objects.
    • Monadic Failure: Implements MonadPlus/Alternative instances, allowing you to decline to handle specific requests and chain multiple handlers together.
    • Early Termination: Allows for early termination of a computation if a specific return value is determined early, preventing unnecessary further monadic processing.

    Additionally, the library provides primitive types and functions for handling HTTP components like cookies, post/query parameters, and utilities for file serving and compression (gzip/zlib).

  3. Follow naming conventions for functions and types

    master

    Use the following casing rules for identifiers:

    • Functions: Use mixed-case (camelCase).
    • Data Types: Use camelCase.
    • Abbreviations: Do not capitalize all letters in abbreviations (e.g., use HttpServer instead of HTTPServer).
    • Exception: Two-letter abbreviations should remain capitalized (e.g., IO).

  4. Organize imports according to Snap style

    master

    Group imports in the following order, separated by a blank line between groups. Within each group, sort modules alphabetically by name:

    1. Standard library imports
    2. Related third-party imports
    3. Local application/library specific imports

    Requirement: Always use explicit import lists or qualified imports for standard and third-party libraries (except for Prelude) to ensure robustness against library changes.

    module MyModule where

import Data.List (sort, group) -- Standard library
import Network.HTTP.Client   -- Third party
import MyProject.Internal    -- Local

  7. Write documentation and comments using Haddock

    master

    Comments should focus on the why rather than the what. Follow these rules:

    • Line Length: Maximum 70 characters for comments.
    • Punctuation & Voice: Use proper sentences (capitalized and punctuated). Write from the perspective of a narrator addressing the user (e.g., "Sends a message..." instead of "Send a message...").
    • Top-Level Definitions: Every top-level function (especially exported ones) and exported data type must be documented using Haddock syntax. Provide a type signature for every function.
    • End-of-Line Comments: Separate end-of-line comments from code using 2 spaces. Align comments for data type definitions.
    -- | Sends a message on a socket. The socket must be in a connected
-- state. Returns the number of bytes sent.
send :: Socket      -- ^ Connected socket
     -> ByteString  -- ^ Data to send
     -> IO Int      -- ^ Bytes sent

  8. Build and run the snap-core testsuite

    master

    To build the test suite, you must first configure Cabal with the --enable-tests flag, then build the project. Once built, you can execute the tests and generate an hpc coverage report using the runTestsAndCoverage.sh script. The coverage report will be placed in dist/hpc.

    cabal configure --enable-tests
cabal build
./runTestsAndCoverage.sh

  9. Follow the Haskell formatting guidelines

    master

    When contributing to Snap projects, follow these formatting rules to maintain consistency:

    • Line Length: Maximum 80 characters for code.
    • Indentation: Use spaces only (tabs are illegal). Use 4 spaces for code blocks. For where clauses, indent the where keyword by 2 spaces and the definitions within it by an additional 2 spaces.
    • Blank Lines: Use one blank line between top-level definitions. Do not put blank lines between a type signature and its function definition. In type class instances, use a blank line between functions if the bodies are large.
    • Whitespace: Surround binary operators with a single space. Do not insert a space after a lambda.
    • Data Declarations: Align constructors in data type definitions. For records, use the following format:
    data Person = Person
    { firstName :: String  -- ^ First name
    , lastName  :: String  -- ^ Last name
    , age       :: Int     -- ^ Age
    } deriving (Eq, Show)
    • Pragmas: Place pragmas immediately following the function they apply to. For data type definitions, place the pragma before the type it applies to.
    • Export Lists: Format module export lists with indentation and grouping as shown in the examples.
    sayHello :: IO ()
sayHello = do
    name <- getLine
    putStrLn $ greeting name
  where
    greeting name = "Hello, " ++ name ++ "!"