-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell interface to the WordNet database
--   
--   A pure-Haskell interface to the WordNet lexical database of English.
--   Depends on the WordNet database, but not on the WordNet source code.
@package WordNet
@version 0.1.2


-- | This is the top level module to the Haskell WordNet interface.
--   
--   This module is maintained at:
--   <a>http://www.isi.edu/~hdaume/HWordNet/</a>.
--   
--   This is the only module in the WordNet package you need to import. The
--   others provide utility functions and primitives that this module is
--   based on.
--   
--   More information about WordNet is available at:
--   <a>http://http://www.cogsci.princeton.edu/~wn/</a>.
module NLP.WordNet

-- | In actuality this type is:
--   
--   <pre>
--   type WN a = (?wne :: WordNetEnv) =&gt; a
--   </pre>
--   
--   but Haddock cannot parse this at this time. type WN a = a
type WN a = (?wne :: WordNetEnv) => a

-- | A Word is just a String.
type Word = String

-- | The basic part of speech type, either a <a>Noun</a>, <a>Verb</a>,
--   <a>Adj</a>ective or <a>Adv</a>erb.
data POS
Noun :: POS
Verb :: POS
Adj :: POS
Adv :: POS

-- | The <a>Overview</a> type is the return type which gives you an
--   overview of a word, for all sense and for all parts of speech.
data Overview

-- | Given an <a>Overview</a>, this will tell you how many noun senses the
--   searched-for word has.
numNounSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many verb senses the
--   searched-for word has.
numVerbSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many adjective senses
--   the searched-for word has.
numAdjSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many adverb senses
--   the searched-for word has.
numAdvSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many times this word
--   was tagged as a noun.
taggedCountNounSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many times this word
--   was tagged as a verb.
taggedCountVerbSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many times this word
--   was tagged as an adjective.
taggedCountAdjSenses :: Overview -> Int

-- | Given an <a>Overview</a>, this will tell you how many times this word
--   was tagged as an adverb.
taggedCountAdvSenses :: Overview -> Int
data WordNetEnv

-- | This will give you the current release of the WordNet databases we are
--   using (if we know).
getReleaseVersion :: WN (Maybe String)

-- | This will give you the directory from which the databases are being
--   read.
getDataDirectory :: WN FilePath

-- | A <a>SenseType</a> is a way of controlling search. Either you specify
--   a certain sense (using <tt>SenseNumber n</tt>, or, since
--   <a>SenseType</a> is an instance of <a>Num</a>, you can juse use
--   <tt>n</tt>) or by searching using all senses, through
--   <a>AllSenses</a>. The <a>Num</a> instance performs standard arithmetic
--   on <a>SenseNumber</a>s, and <a>fromInteger</a> yields a
--   <a>SenseNumber</a> (always), but any arithmetic involving
--   <a>AllSenses</a> returns <a>AllSenses</a>.
data SenseType
AllSenses :: SenseType
SenseNumber :: Int -> SenseType

-- | The basic type which holds search results. Its <a>Show</a> instance
--   simply shows the string corresponding to the associated WordNet
--   synset.
data SearchResult

-- | This provides (maybe) the associated overview for a SearchResult. The
--   <a>Overview</a> is only available if this <a>SearchResult</a> was
--   derived from a real search, rather than <tt>lookupKey</tt>.
srOverview :: SearchResult -> Maybe Overview

-- | This provides (maybe) the associated sense number for a SearchResult.
--   The <a>SenseType</a> is only available if this <a>SearchResult</a> was
--   derived from a real search, rather than <tt>lookupKey</tt>.
srSenseNum :: SearchResult -> Maybe SenseType

-- | This gives the part of speech of a <a>SearchResult</a>
srPOS :: SearchResult -> POS

-- | This gives the definition of the sense of a word in a
--   <a>SearchResult</a>.
srDefinition :: SearchResult -> String

-- | This gives a list of senses the word has.
srSenses :: SearchResult -> [SenseType]

-- | This gives the actual words used to describe the Synset of a search
--   result.
srWords :: SearchResult -> SenseType -> [Word]

-- | This gives all the <a>Form</a>s a word has (i.e., what sort of
--   relations hold between it and other words.
srForms :: SearchResult -> [Form]

-- | This provides a <a>Key</a> (which can be searched for using
--   <tt>lookupKey</tt>) for a <a>SearchResult</a> under a given form. For
--   instance, it can be used to get all <a>Hypernym</a>s of a given word.
srFormKeys :: SearchResult -> Form -> [Key]

-- | This converts a <a>SearchResult</a> into a <a>Key</a>.
srToKey :: SearchResult -> Key

-- | The different types of relations which can hold between WordNet
--   Synsets.
data Form
Antonym :: Form
Hypernym :: Form
Hyponym :: Form
Entailment :: Form
Similar :: Form
IsMember :: Form
IsStuff :: Form
IsPart :: Form
HasMember :: Form
HasStuff :: Form
HasPart :: Form
Meronym :: Form
Holonym :: Form
CauseTo :: Form
PPL :: Form
SeeAlso :: Form
Attribute :: Form
VerbGroup :: Form
Derivation :: Form
Classification :: Form
Class :: Form
Nominalization :: Form
Syns :: Form
Freq :: Form
Frames :: Form
Coords :: Form
Relatives :: Form
HMeronym :: Form
HHolonym :: Form
WNGrep :: Form
OverviewForm :: Form
Unknown :: Form

-- | A <a>Key</a> is a simple pointer into the database, which can be
--   followed using <tt>lookupKey</tt>.
data Key

-- | Takes a WordNet command, initializes the environment and returns the
--   results in the <a>IO</a> monad. WordNet warnings are printed to
--   stderr.
runWordNet :: WN a -> IO a

-- | Takes a WordNet command, initializes the environment and returns the
--   results in the <a>IO</a> monad. WordNet warnings are ignored.
runWordNetQuiet :: WN a -> IO a

-- | Takes a FilePath to the directory holding WordNet and a function to do
--   with warnings and a WordNet command, initializes the environment and
--   returns the results in the <a>IO</a> monad.
runWordNetWithOptions :: Maybe FilePath -> Maybe (String -> Exception -> IO ()) -> WN a -> IO a

-- | Gives you a <a>WordNetEnv</a> which can be passed to <a>runs</a> or
--   used as the implicit parameter to the other WordNet functions.
initializeWordNet :: IO WordNetEnv

-- | Takes a FilePath to the directory holding WordNet and a function to do
--   with warnings, initializes the environment and returns a
--   <a>WordNetEnv</a> as in <a>initializeWordNet</a>.
initializeWordNetWithOptions :: Maybe FilePath -> Maybe (String -> Exception -> IO ()) -> IO WordNetEnv

-- | Closes all the handles associated with the <a>WordNetEnv</a>. Since
--   the functions provided in the <a>NLP.WordNet.WordNet</a> module are
--   <i>lazy</i>, you shouldn't do this until you're really done. Or
--   perhaps not at all (GC will eventually kick in).
closeWordNet :: WordNetEnv -> IO ()

-- | This simply takes a <a>WordNetEnv</a> and provides it as the implicit
--   parameter to the WordNet command.
runs :: WordNetEnv -> WN a -> a

-- | This takes a word and returns an <a>Overview</a> of all its senses for
--   all parts of speech.
getOverview :: WN (Word -> Overview)

-- | This takes an <a>Overview</a> (see <a>getOverview</a>), a <a>POS</a>
--   and a <a>SenseType</a> and returns a list of search results. If
--   <a>SenseType</a> is <a>AllSenses</a>, there will be one
--   <a>SearchResult</a> in the results for each valid sense. If
--   <a>SenseType</a> is a single sense number, there will be at most one
--   element in the result list.
searchByOverview :: WN (Overview -> POS -> SenseType -> [SearchResult])

-- | This takes a <a>Word</a>, a <a>POS</a> and a <a>SenseType</a> and
--   returns the equivalent of first running <a>getOverview</a> and then
--   <a>searchByOverview</a>.
search :: WN (Word -> POS -> SenseType -> [SearchResult])

-- | This takes a <a>Key</a> (see <a>srToKey</a> and <a>srFormKeys</a>) and
--   looks it up in the databse.
lookupKey :: WN (Key -> SearchResult)

-- | This takes a <a>Form</a> and a <a>SearchResult</a> and returns all
--   <a>SearchResult</a> related to the given one by the given <a>Form</a>.
--   
--   For example:
--   
--   <pre>
--   relatedBy Antonym (head (search "happy" Adj 1))
--   [&lt;unhappy&gt;]
--   
--   relatedBy Hypernym (head (search "dog" Noun 1))
--   [&lt;canine canid&gt;]
--   </pre>
relatedBy :: WN (Form -> SearchResult -> [SearchResult])

-- | This is a utility function to build lazy trees from a function and a
--   root.
closure :: (a -> [a]) -> a -> Tree a

-- | This enables <a>Form</a>-based trees to be built.
--   
--   For example:
--   
--   <pre>
--   take 5 $ flatten $ closureOn Antonym (head (search "happy" Adj AllSenses)))
--   [&lt;happy&gt;,&lt;unhappy&gt;,&lt;happy&gt;,&lt;unhappy&gt;,&lt;happy&gt;]
--   </pre>
--   
--   <pre>
--   closureOn Hypernym (head (search "dog" Noun 1)))
--   - &lt;dog domestic_dog Canis_familiaris&gt; --- &lt;canine canid&gt; --- &lt;carnivore&gt;\-- &gt;   --- &lt;placental placental_mammal eutherian eutherian_mammal&gt; --- &lt;mammal&gt;\-- &gt;   --- &lt;vertebrate craniate&gt; --- &lt;chordate&gt; --- &lt;animal animate_being beast\-- &gt;   brute creature fauna&gt; --- &lt;organism being&gt; --- &lt;living_thing animate_thing&gt;\-- &gt;   --- &lt;object physical_object&gt; --- &lt;entity&gt; 
--   </pre>
closureOn :: WN (Form -> SearchResult -> Tree SearchResult)

-- | This function takes an empty bag (in particular, this is to specify
--   what type of search to perform), and the results of two search. It
--   returns (maybe) the lowest point at which the two terms meet in the
--   WordNet hierarchy.
--   
--   For example:
--   
--   <pre>
--   meet emptyQueue (head $ search "cat" Noun 1) (head $ search "dog" Noun 1)
--   Just &lt;carnivore&gt;
--   </pre>
--   
--   <pre>
--   meet emptyQueue (head $ search "run" Verb 1) (head $ search "walk" Verb 1)
--   Just &lt;travel go move locomote&gt;
--   </pre>
meet :: (Bag b (Tree SearchResult)) => WN (b (Tree SearchResult) -> SearchResult -> SearchResult -> Maybe SearchResult)

-- | This function takes an empty bag (see <a>meet</a>), and the results of
--   two searches. It returns (maybe) the lowest point at which the two
--   terms meet in the WordNet hierarchy, as well as the paths leading from
--   each term to this common term.
--   
--   For example:
--   
--   <pre>
--   meetPaths emptyQueue (head $ search "cat" Noun 1) (head $ search "dog" Noun 1)
--   Just ([&lt;cat true_cat&gt;,&lt;feline felid&gt;],&lt;carnivore&gt;,[&lt;canine canid&gt;,&lt;dog domestic_dog Canis_familiaris&gt;])
--   </pre>
--   
--   <pre>
--   meetPaths emptyQueue (head $ search "run" Verb 1) (head $ search "walk" Verb 1)
--   Just ([&lt;run&gt;,&lt;travel_rapidly speed hurry zip&gt;],&lt;travel go move locomote&gt;,[&lt;walk&gt;])
--   </pre>
--   
--   This is marginally less efficient than just using <a>meet</a>, since
--   it uses linear-time lookup for the visited sets, whereas <a>meet</a>
--   uses log-time lookup.
meetPaths :: (Bag b (Tree SearchResult)) => WN (b (Tree SearchResult) -> SearchResult -> SearchResult -> Maybe ([SearchResult], SearchResult, [SearchResult]))
meetSearchPaths :: (Bag b (Tree SearchResult)) => b (Tree SearchResult) -> Tree SearchResult -> Tree SearchResult -> Maybe ([SearchResult], SearchResult, [SearchResult])

-- | A simple bag class for our <a>meet</a> implementation.
class Bag b a
emptyBag :: (Bag b a) => b a
addToBag :: (Bag b a) => b a -> a -> b a
addListToBag :: (Bag b a) => b a -> [a] -> b a
isEmptyBag :: (Bag b a) => b a -> Bool
splitBag :: (Bag b a) => b a -> (a, b a)

-- | An empty queue.
emptyQueue :: Queue a

-- | An empty stack.
emptyStack :: [a]
instance (Show a) => Show (Queue a)
instance Bag Queue a
instance Bag [] a