-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A shortcode extension module for Hakyll -- -- WordPress-style shortcodes for the Hakyll static site generator. @package hakyll-shortcode @version 0.0.2 -- | The types reexported by this module (except for YesNo, which is -- a renaming of Bool) are safe strings. Each is an instance of -- the Validate class, and may only be constructed using the -- validate function. This ensures that the elements of a safe -- string type satisfy the constraints given in their Validate -- instance. module Hakyll.Shortcode.Types -- | The Validate class lets us approximate subtypes of -- String. Instances should not expose a constructor. class Validate t -- | validate acts as a safe constructor. validate :: Validate t => String -> Either String t -- | Apply validate, but map the error message to Nothing. validateMaybe :: (Validate t) => String -> Maybe t -- | Valid CSS class names: alphanumeric, hyphen, or underscore, but the -- first character must be alphanumeric. Note: this type represents only -- a subset of all valid class names. See the CSS grammar. data Css_Class_Name -- | Matches domain names with the https scheme. The regex for this match -- is very simple. data Domain_With_Scheme -- | Strings of six hexadecimal digits. Case insensitive. data Hex_Color_Code -- | ISO 639.1 two-letter language codes. See -- http://www.loc.gov/standards/iso639-2/php/code_list.php. Must -- be constructed with validate. data Iso_639_1_Language_Code -- | Strings consisting only of alphanumeric characters. Must be -- constructed using validate. data Letters_Numbers -- | Strings consisting only of a-z, A-Z, 0-9, -, and _. data Letters_Numbers_Hyphens_Underscores -- | Strings of 64 hexadecimal digits. Case insensitive. data MD5_Digest -- | Either 0, or a nonempty string of decimal digits with no leading -- zeros. data Natural_Number_Base_10 -- | Strings consisting only of a-z, A-Z, 0-9, -, _, ., or ~ characters. -- See RFC 3986, Section 2.3. Must be constructed using -- validate. data RFC_3986_Unreserved_Uri_Characters -- | Type representing Yes or No options for a parameter. A slightly more -- semantically meaningful version of Bool. data YesNo -- | The Yes option. Yes :: YesNo -- | The No option. No :: YesNo -- | Comma-separated lists of valid strings. data CommaSep t -- | Helper functions for constructing URLs and HTML fragments. module Hakyll.Shortcode.Render -- | Simple sum type representing URL schemes. data Scheme HTTPS :: Scheme -- | Helper function for safely building URLs. buildURL :: Scheme -> String -> [String] -> [String] -> [String] -> String class QueryParameter t renderQueryParameter :: QueryParameter t => t -> String -- | Helper function for rendering Maybe Valid shortcode -- parameters as query parameters. queryValid :: (Show t) => Maybe t -> String -> String -- | Helper function for rendering Maybe OneOf shortcode -- parameters as query parameters. queryOneOf :: (QueryParameter t) => Maybe t -> String -- | Helper function for rendering Maybe YesNo shortcode -- parameters as query parameters. queryYesNo :: Maybe YesNo -> String -> String -> String -- | Helper function for rendering Maybe Valid parameters -- as path components. pathValid :: (Show t) => Maybe t -> String -- | Helper function for rendering Maybe YesNo parameters -- as path components. pathYesNo :: Maybe YesNo -> String -> String -> String -- | Helper function for rendering Maybe Valid parameters -- as path components, with a prefix. pathValidPre :: (Show t) => String -> Maybe t -> [String] -- | Helper function for rendering Maybe YesNo parameters -- as path components, with a prefix. pathYesNoPre :: String -> Maybe YesNo -> String -> String -> [String] -- | Helper function for optionally rendering a Maybe as an HTML -- attribute. attrValid :: (Monoid a, Show b) => (AttributeValue -> a) -> Maybe b -> a instance GHC.Show.Show Hakyll.Shortcode.Render.Scheme module Hakyll.Shortcode.Service -- | Class representing abstract shortcode types. class Shortcode t -- | The tag for our shortcode. tag :: Shortcode t => ShortcodeTag t -- | The allowed keys for our shortcode. attributes :: Shortcode t => [ShortcodeAttribute t] -- | An empty shortcode instance. emptycode :: Shortcode t => t -- | Convert t to HTML. embedcode :: Shortcode t => t -> String -- | Type representing the tag of a shortcode; such as youtube. data ShortcodeTag a ShortcodeTag :: String -> ShortcodeTag a -- | Type representing the allowed attributes of a shortcode. These come in -- three forms: Yes/No attributes, which are present or not; Enumerated -- attributes, which take on one of a given list of values; and Validated -- attributes, whose values are strings of a given form. data ShortcodeAttribute t [YesNo] :: String -> (YesNo -> t -> t) -> ShortcodeAttribute t [OneOf] :: String -> [(String, t -> t)] -> ShortcodeAttribute t [Valid] :: (Validate a) => String -> (a -> t -> t) -> ShortcodeAttribute t -- | Generic shortcode expansion. This function almost certainly should not -- be called directly unless you are implementing a new shortcode. expandShortcodes :: (Shortcode t) => t -> String -> String -- | Helper function for reporting errors; this one in case we are trying -- to expand a shortcode with a missing key value. missingError :: String -> String -> String instance GHC.Show.Show (Hakyll.Shortcode.Service.ShortcodeTag a) -- | Do you want to make more shortcodes? Of course, we all do. -- -- This module demonstrates how to implement a type-safe shortcode. The -- basic steps are as follows: -- --
    --
  1. Define a type t which represents the state of a -- shortcode. Typically t will be a record type, and the fields -- should all be Maybes or Lists of instances of the Validate -- class.
    2. --
  2. Define a default instance of your shortcode state. This may -- consist of a bunch of Nothings and []s, or maybe you -- prefer nontrivial defaults. This is the emptycode method of the -- Shortcode class.
    3. --
  3. Declare the usable keys for your shortcode by giving a list of -- 'ShortcodeAttribute t's. This type lets us define our keys in a -- declarative way, sort of like GetOpt. This is the attributes -- method of the Shortcode class.
    4. --
  4. Provide a map t -> String, to be used to convert -- abstract shortcodes to their expanded form. This is the -- embedcode method of the Shortcode class.
    5. --
  5. Last but not least, declare which tag will be used to name your -- shortcode.
    6. --
-- -- And that's it! The shortcode API and type library will take care of -- parsing, validation, and sanitization for you, giving you a function -- String -> String that expands your new shortcode while -- making sure only input conforming to your type model is allowed. -- -- Now let's walk through a sample shortcode module. To read along, view -- the source of this module. module Hakyll.Shortcode.Service.Example -- | This is the function that finds and replaces example -- shortcodes. It is just a type-specific version of the -- expandShortcodes function, that takes a shortcode specification -- and generates a find-and-replace function for it. expandExampleShortcodes :: String -> String instance GHC.Show.Show Hakyll.Shortcode.Service.Example.Beatle instance Hakyll.Shortcode.Service.Shortcode Hakyll.Shortcode.Service.Example.Example -- | This module provides a filter for Hakyll which expands WordPress-style -- shortcodes. To use it, include the line >>= applyShortcodes -- allServices in your compiler. module Hakyll.Shortcode -- | A simple sum type representing the available shortcodes. data ShortcodeService GeoGebra :: ShortcodeService Gravatar :: ShortcodeService YouTube :: ShortcodeService Example :: ShortcodeService -- | Expand shortcodes of each of the provided types. expandShortcodes :: [ShortcodeService] -> String -> String -- | Monadic version of expandShortcodes, for use with Hakyll. applyShortcodes :: (Monad m, Functor f) => [ShortcodeService] -> f String -> m (f String) -- | A list of all the available shortcodes (for convenience). allServices :: [ShortcodeService] instance GHC.Classes.Eq Hakyll.Shortcode.ShortcodeService