-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | An implementation of the Dung argumentation frameworks.
--
-- An implementation of Dung's argumentation frameworks, an abstract
-- argumentation model used to either directly represent conflicting
-- information, or used as a translation target for more complex
-- (structured) argumentation models. For an introduction to Dung's
-- frameworks see
-- http://en.wikipedia.org/wiki/Argumentation_framework and Dung's
-- paper from 1995: "On the acceptability of arguments and its
-- fundamental role in nonmonotonic reasoning, logic programming, and
-- n-person games", Artificial Intelligence 77: 321-357. For the papers
-- accompanying this library see "Towards a framework for the
-- implementation and verification of translations between argumentation
-- models" and "A principled approach to the implementation of
-- argumentation models", available at
-- http://www.cs.nott.ac.uk/~bmv/Dung/.
@package Dung
@version 1.0
-- | This module implements Dung's argumentation frameworks.
module Language.Dung.AF
-- | An abstract argumentation framework is a set of arguments (represented
-- as a list) and an attack relation on these arguments.
data DungAF arg
AF :: [arg] -> [(arg, arg)] -> DungAF arg
-- | Given an argumentation framework, determines whether args (subset of
-- the arguments in the AF), attacks an argument arg (in the AF).
setAttacks :: Eq arg => DungAF arg -> [arg] -> arg -> Bool
-- | Given an argumentation framework, determines the set of arguments that
-- are attacked by an argument (in the AF).
aplus :: Eq arg => DungAF arg -> arg -> [arg]
-- | Given an argumentation framework, determines the set of arguments
-- attacking an argument (in the AF).
amin :: Eq arg => DungAF arg -> arg -> [arg]
-- | Given an argumentation framework, determines the set of arguments that
-- are attacked by the given subset of arguments (in the AF).
argplus :: Eq arg => DungAF arg -> [arg] -> [arg]
-- | Given an argumentation framework, determines the set of arguments that
-- attack a given subset of arguments (in the AF).
argmin :: Eq arg => DungAF arg -> [arg] -> [arg]
-- | Given an argumentation framework, determines whether args (subset of
-- the arguments in the AF) is conflict-free.
conflictFree :: Eq arg => DungAF arg -> [arg] -> Bool
-- | Given an argumentation framework, determines whether an argument is
-- acceptable with respect to a list of args (subset of the
-- arguments in the AF).
acceptable :: Eq arg => DungAF arg -> arg -> [arg] -> Bool
-- | Given an argumentation framework, returns the set of arguments that
-- are acceptable with respect to args (subset of the arguments
-- in the AF).
f :: Eq arg => DungAF arg -> [arg] -> [arg]
-- | Given an argumentation framework, determines whether the set of
-- arguments args (subset of the arguments in the AF) is
-- admissible, i.e. if args is conflictFree and args is a
-- subset of f af args
admissible :: Eq arg => DungAF arg -> [arg] -> Bool
-- | Given a characteristic function f, computes the grounded extension by
-- iterating on the empty set (list) until it reaches a fixpoint.
groundedF :: Eq arg => ([arg] -> [arg]) -> [arg]
-- | Labelling status of arguments.
data Status
In :: Status
Out :: Status
Undecided :: Status
-- | Labelling of arguments.
type Labelling arg = [(arg, Status)]
-- | Given a labelling of arguments, give back the arguments labelled
-- In.
inLab :: Labelling arg -> [arg]
-- | Given a labelling of arguments, give back the arguments labelled
-- Out.
outLab :: Labelling arg -> [arg]
-- | Given a labelling of arguments, give back the arguments labelled
-- Undecided.
undecLab :: Labelling arg -> [arg]
-- | The allIn labelling is a Labelling that labels every argument
-- In.
allIn :: [arg] -> Labelling arg
-- | The allOut labelling is a Labelling that labels every argument
-- Out.
allOut :: [arg] -> Labelling arg
-- | The allUndec labelling is a Labelling that labels every
-- argument Undecided.
allUndec :: [arg] -> Labelling arg
-- | Given a list of arguments that are Out in an argumentation
-- framework af, an argument arg is unattacked if the list of
-- its attackers, ignoring the outs, is empty.
unattacked :: Eq arg => [arg] -> DungAF arg -> arg -> Bool
-- | Given a list of arguments that are In in an argumentation
-- framework af, an argument arg is attacked if there exists an
-- attacker that is In.
attacked :: Eq arg => [arg] -> DungAF arg -> arg -> Bool
-- | Given an argumentation framework, determines the list of attackers of
-- an argument, from a given labelling, returning the labelled attackers.
labAttackers :: Eq arg => DungAF arg -> arg -> Labelling arg -> Labelling arg
-- | Given an AF and Labelling, an argument a (in the AF) is
-- illegally In iff a is labelled In, but not all its
-- attackers are labelled Out.
illegallyIn :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is
-- illegally Out iff a is labelled Out but does not have an
-- attacker labelled In.
illegallyOut :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is
-- illegally Undecided iff a is labelled Undecided but
-- either all its attackers are labelled Out or it has an attacker
-- that is labelled In.
illegallyUndec :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is legally
-- In iff a is labelled In and it's not illegallyIn.
legallyIn :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is legally
-- Out iff a is labelled Out and it's not
-- illegallyOut.
legallyOut :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is legally
-- Undecided iff a is labelled Undecided and it's not
-- illegallyUndec.
legallyUndec :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Given an AF, an admissible labelling is a Labelling without
-- arguments that are illegallyIn and without arguments that are
-- illegallyOut.
isAdmissible :: Eq arg => DungAF arg -> Labelling arg -> Bool
-- | Given an AF, a complete labelling is a labelling without arguments
-- that are illegallyIn, without arguments that are
-- illegallyOut and without arguments that are
-- illegallyUndec.
isComplete :: Eq arg => DungAF arg -> Labelling arg -> Bool
-- | Let labs be a complete labelling, i.e. isComplete af
-- labs, we say that labs is a preferred labelling iff inLab
-- labs is maximal (w.r.t. set inclusion).
isPreferred :: Eq arg => DungAF arg -> [Labelling arg] -> Labelling arg -> Bool
-- | Let labs be a complete labelling, i.e. 'isComplete af labs',
-- we say that labs is a preferred labelling iff undecLab(labs) ==
-- []
isStable :: Eq arg => DungAF arg -> [Labelling arg] -> Labelling arg -> Bool
-- | Let labs be a complete labelling, i.e. isComplete af
-- labs, we say that labs is a semi-stable labelling iff
-- undecLab labs is minimal (w.r.t. set inclusion).
isSemiStable :: Eq arg => DungAF arg -> [Labelling arg] -> Labelling arg -> Bool
-- | Given an AF, a labelling labs and an illegally in argument a in the
-- af, (i.e. illegallyIn af a labs => True), a transition
-- step on a in labs consists of the following: 1. the label of a is
-- changed from In to Out 2. for every b in {a} cup a+, if
-- b is illegally out, then change the label from b from Out to
-- Undecided
transitionStep :: Eq arg => DungAF arg -> Labelling arg -> arg -> Labelling arg
-- | Given an AF, a labelling, labs, is terminated iff labs does not
-- contain any argument that is illegally in, i.e. not (illegallyIn
-- af lab arg) for all arg in labs.
terminatedTransition :: Eq arg => DungAF arg -> Labelling arg -> Bool
-- | Given an AF and Labelling, an argument a (in the AF) is
-- superillegally In iff a is labelled In, and it is
-- attacked by an argument that is legally In or legally
-- Undecided.
superIllegallyIn :: Eq arg => DungAF arg -> Labelling arg -> (arg, Status) -> Bool
-- | Computes the grounded labelling for a Dung argumentation framework,
-- returning a (unique) list of arguments with statuses.
--
-- Based on section 4.1 of Proof Theories and Algorithms for Abstract
-- Argumentation Frameworks by Modgil and Caminada.
grounded :: Eq arg => DungAF arg -> Labelling arg
-- | The grounded extension of an argumentation framework is just the
-- grounded labelling, keeping only those arguments that were labelled
-- In.
groundedExt :: Eq arg => DungAF arg -> [arg]
-- | Computes all complete labellings for a Dung argumentation framework.
-- This is based on Caminada's algorithm for computing semi-stable
-- labellings, with all checks removed.
complete :: Ord arg => DungAF arg -> [Labelling arg]
-- | Computes all preferred labellings for a Dung argumentation framework,
-- by taking the maximally in complete labellings.
preferred :: Ord arg => DungAF arg -> [Labelling arg]
-- | Computes all stable labellings for a Dung argumentation framework, by
-- keeping only those labellings with no Undecided labels.
stable :: Ord arg => DungAF arg -> [Labelling arg]
-- | Computes all semi-stable labellings for a Dung argumentation
-- framework, by taking the minimally undecided complete labellings.
semiStable :: Ord arg => DungAF arg -> [Labelling arg]
-- | The complete extension of an argumentation framework is just the
-- complete labelling, keeping only those arguments that were labelled
-- In.
completeExt :: Ord arg => DungAF arg -> [[arg]]
-- | The preferred extension of an argumentation framework is just the
-- preferred labelling, keeping only those arguments that were labelled
-- In.
preferredExt :: Ord arg => DungAF arg -> [[arg]]
-- | The stable extension of an argumentation framework is just the stable
-- labelling, keeping only those arguments that were labelled In.
stableExt :: Ord arg => DungAF arg -> [[arg]]
-- | The semi-stable extension of an argumentation framework is just the
-- semi-stable labelling, keeping only those arguments that were labelled
-- In.
semiStableExt :: Ord arg => DungAF arg -> [[arg]]
instance Eq arg => Eq (DungAF arg)
instance Show arg => Show (DungAF arg)
instance Eq Status
instance Show Status
instance Ord Status
-- | This is the input module accompanying the implementation of Dung's
-- argumentation frameworks. It defines a simple parser for an
-- argumentation framework that assumes the input file is in
-- CEGARTIX/PrefSat-like format.
--
-- Files are assumed to have one argument or attack on each line, ending
-- in a dot. (Our parser is slightly more relaxed than this and doesn't
-- care about whitespace.)
--
-- att(a1,a2). or arg(a1).
--
-- Argument names are assumed to consist only of letters and numbers.
-- Arguments used in attacks should be declared separately as well.
module Language.Dung.Input
-- | Parses a String containing multiple arguments/attacks. If
-- parsing fails, it propagates the parse error.
parseAF :: String -> Either ParseError (DungAF String)
-- | An AF is parsed by parsing at least one argument or attack, followed
-- by an end of file token.
pAF :: Parser (DungAF String)
-- | This is the output module accompanying the implementation of Dung's
-- argumentation frameworks. It allows an implemented argumentation
-- framework to be outputted to files in a standard format.
--
-- This module currently contains two output format. The strict version
-- is readable by both CEGARTIX and PrefSat. The lax version keeps more
-- of the original formatting.
module Language.Dung.Output
-- | Converts an argument to a CEGARTIX String. All argument names
-- are made into string literals removing extra quotes.
argToCegartix :: Show arg => arg -> String
-- | Converts an attack to a CEGARTIX String. All argument names are
-- made into string literals removing extra quotes.
atkToCegartix :: Show arg => (arg, arg) -> String
-- | Outputs an argumentation frameworks in CEGARTIX/PrefSat format.
toCegartix :: Show arg => DungAF arg -> String
-- | Converts an argument to a CEGARTIX String. All argument names
-- are made into string literals removing extra quotes. Additionally all
-- parentheses are removed.
argToStrictCegartix :: Show arg => arg -> String
-- | Converts an attack to a CEGARTIX String. All argument names are
-- made into string literals removing extra quotes. Additionally all
-- parentheses are removed.
atkToStrictCegartix :: Show arg => (arg, arg) -> String
-- | Outputs an argumentation frameworks in strict CEGARTIX/PrefSat format.
toStrictCegartix :: Show arg => DungAF arg -> String
-- | This is the examples module accompanying the implementation of Dung's
-- argumentation frameworks.
--
-- This module contains a collection of examples, showing how to define
-- arguments, argumentation frameworks and how to use the standard
-- definitions.
--
-- To run these examples, or your own: start GHCi and do the following:
--
--
-- :l Language.Dung.Examples
--
module Language.Dung.Examples
-- | The simplest abstract argument is an argument identifiable by its name
type AbsArg = String
a :: AbsArg
b :: AbsArg
c :: AbsArg
-- | Example AF: A -> B -> C
exampleAF :: DungAF AbsArg
-- | Example AF: A <-> B
--
-- Now follow a few example outputs using the above argumentation
-- frameworks.
--
--
--
-- [a,b] setAttacks c in the argumentation
-- framework exampleAF:
--
--
-- >>> setAttacks exampleAF [a,b] c
-- True
--
--
--
-- >>> setAttacks exampleAF [b,c] a
-- False
--
--
--
-- >>> setAttacks exampleAF2 [] b
-- False
--
--
--
--
-- [a,c] is conflictFree in the argumentation framework
-- exampleAF:
--
--
-- >>> conflictFree exampleAF [a,c]
-- True
--
--
--
-- >>> conflictFree exampleAF [a,b,c]
-- False
--
--
--
-- >>> conflictFree exampleAF2 [a,b]
-- False
--
--
--
--
-- c is acceptable w.r.t. [a,b] in the argumentation
-- framework exampleAF:
--
--
-- >>> acceptable exampleAF c [a,b]
-- True
--
--
--
-- >>> acceptable exampleAF c []
-- False
--
--
--
-- >>> acceptable exampleAF b [a,b,c]
-- False
--
--
--
--
-- [a,b,c] is admissible in the argumentation framework
-- exampleAF:
--
--
-- >>> admissible exampleAF [a,b,c]
-- False
--
--
--
-- >>> admissible exampleAF [a,c]
-- True
--
--
--
-- >>> admissible exampleAF [a]
-- True
--
--
--
--
-- The grounded labelling of the argumentation frameworks
-- exampleAF and exampleAF2:
--
--
-- >>> grounded exampleAF
-- [("A",In),("C",In),("B",Out)]
--
--
--
-- >>> grounded exampleAF2
-- [("A",Undecided),("B",Undecided)]
--
--
--
--
-- The grounded extension of the argumentation frameworks
-- exampleAF and exampleAF2:
--
--
-- >>> groundedExt exampleAF
-- ["A", "C"]
--
-- >>> groundedExt exampleAF2
-- []
--
exampleAF2 :: DungAF AbsArg
-- | fixed point function for a specific argumentation framework, faf =
-- f exampleAF.
--
--
--
-- The grounded extension of the argumentation framework exampleAF
-- using the fixpoint definition:
--
--
-- >>> groundedF faf
-- ["A","C"]
--
--
--
-- >>> groundedF (f exampleAF2)
-- []
--
faf :: [AbsArg] -> [AbsArg]
d :: AbsArg
e :: AbsArg
-- | Left hand side of Fig1. in Caminada. Arguments are: {a,b,c,d}.
-- Attacks: {(a, a), (a, c), (b, c), (c, d)}
exampleAF3 :: DungAF AbsArg
-- | Right hand side of Fig1. in Caminada. Arguments are: {a,b,c,d,e}.
-- Attacks: {(a, b), (b, a), (b, c), (c, d), (d, e), (e, c)}
--
--
--
-- The complete labellings of the argumentation framework
-- exampleAF3 and exampleAF4:
--
--
-- >>> complete exampleAF3
-- [
-- [("A",Undecided),("B",In),("C",Out),("D",In)]
-- ]
--
--
--
-- >>> complete exampleAF4
-- [
-- [("A",Out),("B",In),("C",Out),("D",In),("E",Out)],
-- [("A",In),("B",Out),("C",Undecided),("D",Undecided),("E",Undecided)],
-- [("A",Out),("B",In),("C",Out),("D",Undecided),("E",Undecided)]
-- ]
--
--
--
--
-- The complete extensions of the argumentation frameworks
-- exampleAF3 and exampleAF4:
--
--
-- >>> completeExt exampleAF3
-- [
-- ["B","D"]
-- ]
--
-- >>> completeExt exampleAF4
-- [
-- ["B","D"],
-- ["A"],
-- ["B"]
-- ]
--
--
--
--
-- The semi-stable labellings of the argumentation framework
-- exampleAF3 and exampleAF4:
--
--
-- >>> semiStable exampleAF3
-- [
-- [("A",Undecided),("B",In),("C",Out),("D",In)]
-- ]
--
--
--
-- >>> semiStable exampleAF4
-- [
-- [("A",Out),("B",In),("C",Out),("D",In),("E",Out)],
-- ]
--
--
--
--
-- The complete extensions of the argumentation frameworks
-- exampleAF3 and exampleAF4:
--
--
-- >>> semiStableExt exampleAF3
-- [
-- ["B","D"]
-- ]
--
-- >>> semiStableExt exampleAF4
-- [
-- ["B","D"],
-- ]
--
exampleAF4 :: DungAF AbsArg
-- | Parsed example as given on the CEGARTIX webpage:
-- http://www.dbai.tuwien.ac.at/proj/argumentation/cegartix/.
--
--
-- arg(a).
-- arg(b).
-- arg(c).
-- arg(d).
-- arg(e).
-- arg(f).
-- arg(g).
-- att(a,b).
-- att(c,b).
-- att(c,d).
-- att(d,c).
-- att(d,e).
-- att(e,g).
-- att(f,e).
-- att(g,f).
--
--
-- This is given as a literal string to parseAF.
exampleAF5 :: DungAF AbsArg
-- | Output String corresponding to exampleAF, i.e.
-- toCegartix exampleAF.
--
--
-- >>> putStr output
-- arg("A").
-- arg("B").
-- arg("C").
-- att("A","B").
-- att("B","C").
--
output :: String
-- | Output String corresponding to exampleAF2, i.e.
-- toCegartix exampleAF2.
--
--
-- >>> putStr output2
-- arg("A").
-- arg("B").
-- att("A","B").
-- att("B","A").
--
output2 :: String
-- | Output String corresponding to exampleAF3, i.e.
-- toCegartix exampleAF3.
--
--
-- >>> putStr output3
-- arg("A").
-- arg("B").
-- arg("C").
-- arg("D").
-- att("A","A").
-- att("A","C").
-- att("B","C").
-- att("C","D").
--
output3 :: String
-- | Output String corresponding to exampleAF4, i.e.
-- toCegartix exampleAF4.
--
--
-- >>> putStr output4
-- arg("A").
-- arg("B").
-- arg("C").
-- arg("D").
-- arg("E").
-- att("A","B").
-- att("B","A").
-- att("B","C").
-- att("C","D").
-- att("D","E").
-- att("E","C").
--
output4 :: String
-- | Output String corresponding to exampleAF5, i.e.
-- toCegartix exampleAF5.
output5 :: String