diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ successfully building the documentation, so I also publish the documentation on [GitHub pages](https://pharpend.github.io/eros-haddock) -# Usage - v.0.5.1.0 +# Usage - v.0.5.2.0 -This is a usage guide for version 0.5.1.0. There will be more up-to-date usage +This is a usage guide for version 0.5.2.0. There will be more up-to-date usage guides as more versions come, hopefully. To install, add `eros >=0.5 && <0.6` to the `build-depends` field in your @@ -32,6 +32,115 @@ hurt to check [eros on Hackage](http://hackage.haskell.org/package/eros). If that doesn't work, I publish the documentation [here](https://pharpend.github.io/eros-haddock). + +## Using `Text.Eros` + +The basic idea is you take a `Message` type, and check it against a `PhraseMap`, +using `messageScore`. `Message` is actually just a type alias for `Tl.Text`, so +just enable the `OverloadedStrings` extension, and pretend you're using normal +strings. + +In GHCi, + +`:set -XOverloadedStrings` + +`import Text.Eros` + +In a file, + +``` {.haskell} + {-# LANGUAGE OverloadedStrings #-} + import Text.Eros +``` + +### Constructing `PhraseMap`s + +A `PhraseMap` is just a `Phraselist` marshaled into the more Haskell-friendly +`Ms.Map` type. + +Eros provides a large number of `Phraselist`s. + +``` {.haskell} + data ErosList = Chat + | Conspiracy + | DrugAdvocacy + | Forums + | Gambling + | Games + | Gore + | IdTheft + | IllegalDrugs + | Intolerance + | LegalDrugs + | Malware + | Music + | News + | Nudism + | Peer2Peer + | Personals + | Pornography + | Proxies + | SecretSocieties + | SelfLabeling + | Sport + | Translation + | UpstreamFilter + | Violence + | WarezHacking + | Weapons + | Webmail + deriving (Eq) +``` + +The easiest way to marshal a `Phraselist` into a `PhraseMap` is to use the +`readPhraseMap` function. + +``` {.haskell} + readPhraseMap :: Phraselist t => t -> IO PhraseMap +``` + +Use it like this + +`pornMap <- readPhraseMap Pornography` +`30` + +Internally, `readPhraseMap` reads JSON data containing the `Phraselist`, +marshals it into a list of `PhraseAlmostTree`s, converts those into a +`PhraseForsest`, and then into a `PhraseMap`. + +You can obviously use `mkMap` and `readPhraselist` to do it yourself, but it's a +lot easier to just use `readPhraseMap`. + +You can then use `messageScore` to see the `Score` (actually an `Int`) of each +message. + +`messageScore "Go fuck yourself." pornMap` + +`messageScore` is not case sensitive, so `go fUck YoUrself` returns the same +score as `go fuck yourself`, and so on. + +If you want to use multiple eros lists, do something like this + +`let myLists = [Chat, Pornography, Weapons]` + +`myMaps <- mapM readPhraseMap myLists` + +`map (messageScore "Go fuck yourself") myMaps` +`[0, 30, 0]` + +### Using your own phraselists + +I haven't added *good* support in for this yet, but there still is support +nonetheless. Your phraselist needs to be in JSON, in accordance with the +Phraselist schema (I'm too lazy to find a link to it). + +``` {.haskell} + data MyList = MyList + instance Phraselist MyList where + phraselistPath MyList = "/path/to/phraselist" +``` + +You can then do the normal stuff with `messageScore` and `readPhraseMap`. # Contributing diff --git a/eros.cabal b/eros.cabal --- a/eros.cabal +++ b/eros.cabal @@ -1,5 +1,5 @@ name: eros -version: 0.5.1.0 +version: 0.5.2.0 synopsis: A text censorship library. description: A Haskell library for censoring text, using @@ -31,11 +31,11 @@ library exposed-modules: Text.Eros - other-modules: - Paths_eros , Text.Eros.Message , Text.Eros.Phrase , Text.Eros.Phraselist + other-modules: + Paths_eros other-extensions: FlexibleInstances , OverloadedStrings diff --git a/src/Text/Eros.hs b/src/Text/Eros.hs new file mode 100644 --- /dev/null +++ b/src/Text/Eros.hs @@ -0,0 +1,129 @@ +{-| +Module : Text.Eros +Description : Capstone Module for eros +Copyright : 2014, Peter Harpending. +License : BSD3 +Maintainer : Peter Harpending +Stability : experimental +Portability : archlinux + +This module serves as a bit of a capstone to the whole eros +library. The idea being you can just import this module, and get +all of the functions from all the rest of eros. + +You will have to look in the documentation for the sub-modules for +the functions. I haven't quite figured out how to get the +documentation to show up here yet. + += How to use this library + +The basic idea is you take a 'Message' type, and check it against a +'PhraseMap', using 'messageScore'. 'Message' is actually just a type +alias for 'Tl.Text', so just enable the 'OverloadedStrings' extension, +and pretend you're using normal strings. + +In GHCi, + +>>> :set -XOverloadedStrings +>>> import Text.Eros + +In a file, + +> {\-# LANGUAGE OverloadedStrings #-\} +> import Text.Eros + +== Constructing 'PhraseMap's + +A 'PhraseMap' is just a 'Phraselist' marshaled into the more +Haskell-friendly 'Ms.Map' type. + +Eros provides a large number of 'Phraselist's. + +> data ErosList = Chat +> | Conspiracy +> | DrugAdvocacy +> | Forums +> | Gambling +> | Games +> | Gore +> | IdTheft +> | IllegalDrugs +> | Intolerance +> | LegalDrugs +> | Malware +> | Music +> | News +> | Nudism +> | Peer2Peer +> | Personals +> | Pornography +> | Proxies +> | SecretSocieties +> | SelfLabeling +> | Sport +> | Translation +> | UpstreamFilter +> | Violence +> | WarezHacking +> | Weapons +> | Webmail +> deriving (Eq) + + +The easiest way to marshal a 'Phraselist' into a 'PhraseMap' is to use +the 'readPhraseMap' function. + +> readPhraseMap :: Phraselist t => t -> IO PhraseMap + +Use it like this + +>>> pornMap <- readPhraseMap Pornography +30 + +Internally, 'readPhraseMap' reads JSON data containing the +'Phraselist', marshals it into a list of 'PhraseAlmostTree's, converts +those into a 'PhraseForsest', and then into a 'PhraseMap'. + +You can obviously use 'mkMap' and 'readPhraselist' to do it yourself, +but it's a lot easier to just use 'readPhraseMap'. + +You can then use 'messageScore' to see the 'Score' (actually an 'Int') +of each message. + +>>> messageScore "Go fuck yourself." pornMap + +'messageScore' is not case sensitive, so @"go fUck YoUrself"@ returns +the same score as @"go fuck yourself"@, and so on. + +If you want to use multiple eros lists, do something like this + +>>> let myLists = [Chat, Pornography, Weapons] +>>> myMaps <- mapM readPhraseMap myLists +>>> map (messageScore "Go fuck yourself") myMaps +[0, 30, 0] + += Using your own phraselists + +I haven't added /good/ support in for this yet, but there still is +support nonetheless. Your phraselist needs to be in JSON, in +accordance with the Phraselist schema (I'm too lazy to find a link to +it). + +> data MyList = MyList +> instance Phraselist MyList where +> phraselistPath MyList = "/path/to/phraselist" + +You can then do the normal stuff with 'messageScore' and 'readPhraseMap'. + +-} +module Text.Eros (module Text.Eros) where + +import Text.Eros.Message as Text.Eros +import Text.Eros.Phrase as Text.Eros +import Text.Eros.Phraselist as Text.Eros + +import qualified Data.Map as Ms +import qualified Data.Text.Lazy as Tl +import Text.Eros.Message +import Text.Eros.Phraselist +import Text.Eros.Phrase diff --git a/src/Text/Eros.lhs b/src/Text/Eros.lhs deleted file mode 100644 --- a/src/Text/Eros.lhs +++ /dev/null @@ -1,22 +0,0 @@ -| -Module : Text.Eros -Description : Capstone Module for eros -Copyright : 2014, Peter Harpending. -License : BSD3 -Maintainer : Peter Harpending -Stability : experimental -Portability : archlinux - -This module serves as a bit of a capstone to the whole eros -library. The idea being you can just import this module, and get -all of the functions from all the rest of eros. - -You will have to look in the documentation for the sub-modules for -the functions. I haven't quite figured out how to get the -documentation to show up here yet. - -> module Text.Eros (module Text.Eros) where - -> import Text.Eros.Message as Text.Eros -> import Text.Eros.Phrase as Text.Eros -> import Text.Eros.Phraselist as Text.Eros diff --git a/src/Text/Eros/Phraselist.hs b/src/Text/Eros/Phraselist.hs --- a/src/Text/Eros/Phraselist.hs +++ b/src/Text/Eros/Phraselist.hs @@ -62,7 +62,7 @@ -- |Load a 'Phraselist' directly into a 'PhraseMap' readPhraseMap :: Phraselist t => t -> IO PhraseMap -readPhraseMap plist = fmap mkMap $ readPhraselist plist +readPhraseMap plist = mkMap <$> readPhraselist plist -- |Read the phraselist from disk servePhraselist :: Phraselist t => t -> IO B.ByteString @@ -111,68 +111,7 @@ | WarezHacking | Weapons | Webmail - ------------------------------------- --- Okay, this is the boring stuff -- ------------------------------------- - -instance Eq ErosList where - (==) Chat Chat = True - (==) Conspiracy Conspiracy = True - (==) DrugAdvocacy DrugAdvocacy = True - (==) Forums Forums = True - (==) Gambling Gambling = True - (==) Games Games = True - (==) Gore Gore = True - (==) IdTheft IdTheft = True - (==) IllegalDrugs IllegalDrugs = True - (==) Intolerance Intolerance = True - (==) LegalDrugs LegalDrugs = True - (==) Malware Malware = True - (==) Music Music = True - (==) News News = True - (==) Nudism Nudism = True - (==) Peer2Peer Peer2Peer = True - (==) Personals Personals = True - (==) Pornography Pornography = True - (==) Proxies Proxies = True - (==) SecretSocieties SecretSocieties = True - (==) SelfLabeling SelfLabeling = True - (==) Sport Sport = True - (==) Translation Translation = True - (==) UpstreamFilter UpstreamFilter = True - (==) Violence Violence = True - (==) WarezHacking WarezHacking = True - (==) Weapons Weapons = True - (==) Webmail Webmail = True - (==) Chat _ = False - (==) Conspiracy _ = False - (==) DrugAdvocacy _ = False - (==) Forums _ = False - (==) Gambling _ = False - (==) Games _ = False - (==) Gore _ = False - (==) IdTheft _ = False - (==) IllegalDrugs _ = False - (==) Intolerance _ = False - (==) LegalDrugs _ = False - (==) Malware _ = False - (==) Music _ = False - (==) News _ = False - (==) Nudism _ = False - (==) Peer2Peer _ = False - (==) Personals _ = False - (==) Pornography _ = False - (==) Proxies _ = False - (==) SecretSocieties _ = False - (==) SelfLabeling _ = False - (==) Sport _ = False - (==) Translation _ = False - (==) UpstreamFilter _ = False - (==) Violence _ = False - (==) WarezHacking _ = False - (==) Weapons _ = False - (==) Webmail _ = False + deriving (Eq) -- |A list of phraselists we provide. erosLists :: [ErosList]