{-# LANGUAGE PostfixOperators #-}
-- | Defines functions to create traceability matrices in SRS documents.
module Drasil.SRS.DocumentLanguage.TraceabilityMatrix (
  generateTraceTableView, traceMHeader, layoutUIDs, traceMReferees,
  traceMReferrers, traceMColumns, traceMIntro, traceView, traceViewCC
) where

-- General Haskell
import Control.Lens ((^.))
import Data.Containers.ListUtils (nubOrd)
import qualified Data.Map as Map

-- General Drasil
import Drasil.Database (UID, HasUID(..))
import Drasil.Database.SearchTools (defResolve', findAllConcInsts, DomDefn(domain))
import Language.Drasil
import Language.Drasil.Document
import Drasil.System (SmithEtAlSRS, systemdb, traceLookup, refbyTable, traceTable)
import qualified Language.Drasil.Sentence.Combinators as S

-- Vocabulary
import Drasil.Metadata.Documentation (purpose, component, dependency,
  item, reference, traceyMatrix)

-- Other docLang
import Drasil.SRS.DocumentLanguage.Definitions (helpToRefField, TraceViewCat)

-- FIXME: Everything in this file needs to be re-written for readability.

-- * Main Functions

-- | Generalized traceability matrix introduction: appends references to the traceability matrices in 'Sentence' form
-- and wraps in 'Contents'. Usually references the four tables generally found in this section (in order of being mentioned).
traceMIntro :: [LabelledContent] -> [Sentence] -> Contents
traceMIntro :: [LabelledContent] -> [Sentence] -> Contents
traceMIntro [LabelledContent]
refs [Sentence]
trailings = UnlabelledContent -> Contents
UlC (UnlabelledContent -> Contents) -> UnlabelledContent -> Contents
forall a b. (a -> b) -> a -> b
$ RawContent -> UnlabelledContent
ulcc (RawContent -> UnlabelledContent)
-> RawContent -> UnlabelledContent
forall a b. (a -> b) -> a -> b
$ Sentence -> RawContent
Paragraph (Sentence -> RawContent) -> Sentence -> RawContent
forall a b. (a -> b) -> a -> b
$ [Sentence] -> Sentence
foldlSent [IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
purpose
        Sentence -> Sentence -> Sentence
`S.the_ofTheC` IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
traceyMatrix, String -> Sentence
S String
"is to provide easy", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
reference,
        String -> Sentence
S String
"on what has to be additionally modified if a certain",
        IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
component, String -> Sentence
S String
"is changed. Every time a", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
component,
        String -> Sentence
S String
"is changed, the", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
item, String -> Sentence
S String
"in the column of that",
        IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
component, String -> Sentence
S String
"that are marked with an", Sentence -> Sentence
Quote (String -> Sentence
S String
"X"),
        String -> Sentence
S String
"should be modified as well"] Sentence -> Sentence -> Sentence
+:+ [Sentence] -> Sentence
foldlSent_ ((LabelledContent -> Sentence -> Sentence)
-> [LabelledContent] -> [Sentence] -> [Sentence]
forall a b c. (a -> b -> c) -> [a] -> [b] -> [c]
zipWith LabelledContent -> Sentence -> Sentence
forall a.
(Referable a, HasShortName a) =>
a -> Sentence -> Sentence
tableShows [LabelledContent]
refs [Sentence]
trailings)

-- | Generates a traceability table. Takes a 'UID' for the table, a description ('Sentence'), columns ('TraceViewCat'), rows ('TraceViewCat'), and 'System'.
generateTraceTableView :: UID -> Sentence -> [TraceViewCat] -> [TraceViewCat] -> SmithEtAlSRS -> LabelledContent
generateTraceTableView :: UID
-> Sentence
-> [TraceViewCat]
-> [TraceViewCat]
-> SmithEtAlSRS
-> LabelledContent
generateTraceTableView UID
u Sentence
desc [TraceViewCat]
cols [TraceViewCat]
rows SmithEtAlSRS
c = UID -> RawContent -> LabelledContent
llccTab' UID
u (RawContent -> LabelledContent) -> RawContent -> LabelledContent
forall a b. (a -> b) -> a -> b
$ [Sentence] -> [[Sentence]] -> Sentence -> Bool -> RawContent
Table
  (Sentence
EmptyS Sentence -> [Sentence] -> [Sentence]
forall a. a -> [a] -> [a]
: ([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMColHeader [UID] -> [UID]
colf SmithEtAlSRS
c)
  ([Sentence] -> [[UID]] -> [UID] -> [[Sentence]]
forall a. Eq a => [Sentence] -> [[a]] -> [a] -> [[Sentence]]
makeTMatrix (([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMRowHeader [UID] -> [UID]
rowf SmithEtAlSRS
c) (([UID] -> [UID]) -> ([UID] -> [UID]) -> SmithEtAlSRS -> [[UID]]
traceMColumns [UID] -> [UID]
colf [UID] -> [UID]
rowf SmithEtAlSRS
c) ([UID] -> [[Sentence]]) -> [UID] -> [[Sentence]]
forall a b. (a -> b) -> a -> b
$ ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferees [UID] -> [UID]
colf SmithEtAlSRS
c)
  (IdeaDict -> Sentence -> Sentence
forall c. NamedIdea c => c -> Sentence -> Sentence
showingCxnBw IdeaDict
traceyMatrix Sentence
desc) Bool
True
    where
    colf :: [UID] -> [UID]
colf = [TraceViewCat] -> SmithEtAlSRS -> [UID] -> [UID]
layoutUIDs [TraceViewCat]
cols SmithEtAlSRS
c
    rowf :: [UID] -> [UID]
rowf = [TraceViewCat] -> SmithEtAlSRS -> [UID] -> [UID]
layoutUIDs [TraceViewCat]
rows SmithEtAlSRS
c

-- * Helper Functions

-- | Helper that finds the traceability matrix references (things being referenced).
traceMReferees :: ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferees :: ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferees [UID] -> [UID]
f = [UID] -> [UID]
f ([UID] -> [UID])
-> (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [UID] -> [UID]
forall a. Ord a => [a] -> [a]
nubOrd ([UID] -> [UID])
-> (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Map UID [UID] -> [UID]
forall k a. Map k a -> [k]
Map.keys (Map UID [UID] -> [UID])
-> (SmithEtAlSRS -> Map UID [UID]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (SmithEtAlSRS
-> Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
-> Map UID [UID]
forall s a. s -> Getting a s a -> a
^. Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
forall c. HasSmithEtAlSRS c => Lens' c (Map UID [UID])
Lens' SmithEtAlSRS (Map UID [UID])
refbyTable)

-- | Helper that finds the traceability matrix references (things that are referring to other things).
traceMReferrers :: ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferrers :: ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferrers [UID] -> [UID]
f = [UID] -> [UID]
f ([UID] -> [UID])
-> (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [UID] -> [UID]
forall a. Ord a => [a] -> [a]
nubOrd ([UID] -> [UID])
-> (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [[UID]] -> [UID]
forall (t :: * -> *) a. Foldable t => t [a] -> [a]
concat ([[UID]] -> [UID])
-> (SmithEtAlSRS -> [[UID]]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Map UID [UID] -> [[UID]]
forall k a. Map k a -> [a]
Map.elems (Map UID [UID] -> [[UID]])
-> (SmithEtAlSRS -> Map UID [UID]) -> SmithEtAlSRS -> [[UID]]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (SmithEtAlSRS
-> Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
-> Map UID [UID]
forall s a. s -> Getting a s a -> a
^. Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
forall c. HasSmithEtAlSRS c => Lens' c (Map UID [UID])
Lens' SmithEtAlSRS (Map UID [UID])
refbyTable)

-- | Helper that finds the header of a traceability matrix.
traceMHeader :: (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMHeader :: (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMHeader SmithEtAlSRS -> [UID]
f SmithEtAlSRS
c = (UID -> Sentence) -> [UID] -> [Sentence]
forall a b. (a -> b) -> [a] -> [b]
map (UID -> ChunkDB -> Sentence
`helpToRefField` (SmithEtAlSRS
c SmithEtAlSRS -> Getting ChunkDB SmithEtAlSRS ChunkDB -> ChunkDB
forall s a. s -> Getting a s a -> a
^. Getting ChunkDB SmithEtAlSRS ChunkDB
forall c. HasSystemMeta c => Lens' c ChunkDB
Lens' SmithEtAlSRS ChunkDB
systemdb)) ([UID] -> [Sentence]) -> [UID] -> [Sentence]
forall a b. (a -> b) -> a -> b
$ SmithEtAlSRS -> [UID]
f SmithEtAlSRS
c

-- | Helper that finds the headers of the traceability matrix columns.
traceMColHeader :: ([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMColHeader :: ([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMColHeader [UID] -> [UID]
f = (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMHeader (([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferees [UID] -> [UID]
f)

-- | Helper that finds the headers of the traceability matrix rows.
traceMRowHeader :: ([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMRowHeader :: ([UID] -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMRowHeader [UID] -> [UID]
f = (SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> [Sentence]
traceMHeader (([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferrers [UID] -> [UID]
f)

-- | Helper that makes the columns of a traceability matrix.
traceMColumns :: ([UID] -> [UID]) -> ([UID] -> [UID]) -> SmithEtAlSRS -> [[UID]]
traceMColumns :: ([UID] -> [UID]) -> ([UID] -> [UID]) -> SmithEtAlSRS -> [[UID]]
traceMColumns [UID] -> [UID]
fc [UID] -> [UID]
fr SmithEtAlSRS
c = (UID -> [UID]) -> [UID] -> [[UID]]
forall a b. (a -> b) -> [a] -> [b]
map ((\[UID]
u -> (UID -> Bool) -> [UID] -> [UID]
forall a. (a -> Bool) -> [a] -> [a]
filter (UID -> [UID] -> Bool
forall a. Eq a => a -> [a] -> Bool
forall (t :: * -> *) a. (Foldable t, Eq a) => a -> t a -> Bool
`elem` [UID]
u) ([UID] -> [UID]) -> [UID] -> [UID]
forall a b. (a -> b) -> a -> b
$ [UID] -> [UID]
fc [UID]
u) ([UID] -> [UID]) -> (UID -> [UID]) -> UID -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (UID -> SmithEtAlSRS -> [UID]) -> SmithEtAlSRS -> UID -> [UID]
forall a b c. (a -> b -> c) -> b -> a -> c
flip UID -> SmithEtAlSRS -> [UID]
traceLookup SmithEtAlSRS
c) ([UID] -> [[UID]]) -> [UID] -> [[UID]]
forall a b. (a -> b) -> a -> b
$ ([UID] -> [UID]) -> SmithEtAlSRS -> [UID]
traceMReferrers [UID] -> [UID]
fr SmithEtAlSRS
c

-- | Helper that makes references of the form "@reference@ shows the dependencies of @something@".
tableShows :: (Referable a, HasShortName a) => a -> Sentence -> Sentence
tableShows :: forall a.
(Referable a, HasShortName a) =>
a -> Sentence -> Sentence
tableShows a
r Sentence
end = a -> Sentence
forall r.
(IsChunk r, HasRefAddress r, HasShortName r) =>
r -> Sentence
refS a
r Sentence -> Sentence -> Sentence
+:+ String -> Sentence
S String
"shows the" Sentence -> Sentence -> Sentence
+:+ IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
dependency Sentence -> Sentence -> Sentence
`S.ofThe` (Sentence
end !.)

-- | Helper that finds the layout 'UID's of a traceability matrix.
layoutUIDs :: [TraceViewCat] -> SmithEtAlSRS -> [UID] -> [UID]
layoutUIDs :: [TraceViewCat] -> SmithEtAlSRS -> [UID] -> [UID]
layoutUIDs [TraceViewCat]
a SmithEtAlSRS
c [UID]
e = (TraceViewCat -> [UID]) -> [TraceViewCat] -> [UID]
forall (t :: * -> *) a b. Foldable t => (a -> [b]) -> t a -> [b]
concatMap ((UID -> Bool) -> [UID] -> [UID]
forall a. (a -> Bool) -> [a] -> [a]
filter (UID -> [UID] -> Bool
forall a. Eq a => a -> [a] -> Bool
forall (t :: * -> *) a. (Foldable t, Eq a) => a -> t a -> Bool
`elem` (Map UID [UID] -> [UID]
forall k a. Map k a -> [k]
Map.keys (Map UID [UID] -> [UID]) -> Map UID [UID] -> [UID]
forall a b. (a -> b) -> a -> b
$ SmithEtAlSRS
c SmithEtAlSRS
-> Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
-> Map UID [UID]
forall s a. s -> Getting a s a -> a
^. Getting (Map UID [UID]) SmithEtAlSRS (Map UID [UID])
forall c. HasSmithEtAlSRS c => Lens' c (Map UID [UID])
Lens' SmithEtAlSRS (Map UID [UID])
traceTable)) ([UID] -> [UID])
-> (TraceViewCat -> [UID]) -> TraceViewCat -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (\ TraceViewCat
x -> TraceViewCat
x [UID]
e SmithEtAlSRS
c)) [TraceViewCat]
a

-- | Helper that filters a traceability matrix given a predicate and a 'ChunkDB' lens field.
traceViewFilt :: HasUID a => (a -> Bool) -> (SmithEtAlSRS -> [a]) -> TraceViewCat
traceViewFilt :: forall a.
HasUID a =>
(a -> Bool) -> (SmithEtAlSRS -> [a]) -> TraceViewCat
traceViewFilt a -> Bool
f SmithEtAlSRS -> [a]
table [UID]
_ = (a -> UID) -> [a] -> [UID]
forall a b. (a -> b) -> [a] -> [b]
map (a -> Getting UID a UID -> UID
forall s a. s -> Getting a s a -> a
^. Getting UID a UID
forall c. HasUID c => Getter c UID
Getter a UID
uid) ([a] -> [UID]) -> (SmithEtAlSRS -> [a]) -> SmithEtAlSRS -> [UID]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (a -> Bool) -> [a] -> [a]
forall a. (a -> Bool) -> [a] -> [a]
filter a -> Bool
f ([a] -> [a]) -> (SmithEtAlSRS -> [a]) -> SmithEtAlSRS -> [a]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. SmithEtAlSRS -> [a]
table

-- | Helper that is similar to 'traceViewFilt', but the filter is always 'True'.
traceView :: HasUID a => (SmithEtAlSRS -> [a]) -> TraceViewCat
traceView :: forall a. HasUID a => (SmithEtAlSRS -> [a]) -> TraceViewCat
traceView = (a -> Bool) -> (SmithEtAlSRS -> [a]) -> TraceViewCat
forall a.
HasUID a =>
(a -> Bool) -> (SmithEtAlSRS -> [a]) -> TraceViewCat
traceViewFilt (Bool -> a -> Bool
forall a b. a -> b -> a
const Bool
True)

-- | Turns a 'Concept' into a 'TraceViewCat' via its domain.
traceViewCC :: Concept c => c -> TraceViewCat
traceViewCC :: forall c. Concept c => c -> TraceViewCat
traceViewCC c
dom [UID]
u SmithEtAlSRS
s = (ConceptInstance -> Bool)
-> (SmithEtAlSRS -> [ConceptInstance]) -> TraceViewCat
forall a.
HasUID a =>
(a -> Bool) -> (SmithEtAlSRS -> [a]) -> TraceViewCat
traceViewFilt (UID -> UID -> Bool
isDomUnder (c
dom c -> Getting UID c UID -> UID
forall s a. s -> Getting a s a -> a
^. Getting UID c UID
forall c. HasUID c => Getter c UID
Getter c UID
uid) (UID -> Bool)
-> (ConceptInstance -> UID) -> ConceptInstance -> Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [UID] -> UID
sDom ([UID] -> UID)
-> (ConceptInstance -> [UID]) -> ConceptInstance -> UID
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ConceptInstance -> [UID]
forall c. ConceptDomain c => c -> [UID]
cdom) (ChunkDB -> [ConceptInstance]
findAllConcInsts (ChunkDB -> [ConceptInstance])
-> (SmithEtAlSRS -> ChunkDB) -> SmithEtAlSRS -> [ConceptInstance]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (SmithEtAlSRS -> Getting ChunkDB SmithEtAlSRS ChunkDB -> ChunkDB
forall s a. s -> Getting a s a -> a
^. Getting ChunkDB SmithEtAlSRS ChunkDB
forall c. HasSystemMeta c => Lens' c ChunkDB
Lens' SmithEtAlSRS ChunkDB
systemdb)) [UID]
u SmithEtAlSRS
s
  where
    isDomUnder :: UID -> UID -> Bool
    isDomUnder :: UID -> UID -> Bool
isDomUnder UID
filtDom UID
curr
      | UID
filtDom UID -> UID -> Bool
forall a. Eq a => a -> a -> Bool
== UID
curr = Bool
True
      | Bool -> Bool
not (Bool -> Bool) -> Bool -> Bool
forall a b. (a -> b) -> a -> b
$ [UID] -> Bool
forall a. [a] -> Bool
forall (t :: * -> *) a. Foldable t => t a -> Bool
null ([UID] -> Bool) -> [UID] -> Bool
forall a b. (a -> b) -> a -> b
$ UID -> [UID]
getDom UID
curr = UID -> UID -> Bool
isDomUnder UID
filtDom ([UID] -> UID
sDom ([UID] -> UID) -> [UID] -> UID
forall a b. (a -> b) -> a -> b
$ UID -> [UID]
getDom UID
curr)
      | Bool
otherwise = Bool
False
    getDom :: UID -> [UID]
    getDom :: UID -> [UID]
getDom UID
curr = DomDefn -> [UID]
domain (DomDefn -> [UID]) -> DomDefn -> [UID]
forall a b. (a -> b) -> a -> b
$ ChunkDB -> UID -> DomDefn
defResolve' (SmithEtAlSRS
s SmithEtAlSRS -> Getting ChunkDB SmithEtAlSRS ChunkDB -> ChunkDB
forall s a. s -> Getting a s a -> a
^. Getting ChunkDB SmithEtAlSRS ChunkDB
forall c. HasSystemMeta c => Lens' c ChunkDB
Lens' SmithEtAlSRS ChunkDB
systemdb) UID
curr