-- | Defines concepts used in the field of software.
module Data.Drasil.Concepts.Software where

import Language.Drasil
import qualified Language.Drasil.Sentence.Combinators as S

import Data.Drasil.Concepts.Computation (algorithm, dataStruct, inParam)
import Data.Drasil.Concepts.Documentation (input_, physical, physicalConstraint,
  srs, softwareConstraint, quantity)
import Data.Drasil.Concepts.Math (equation)

-- * Common Software Concepts

-- | Collects all software-related concepts.
softwarecon :: [ConceptChunk]
softwarecon :: [ConceptChunk]
softwarecon = [ConceptChunk
correctness, ConceptChunk
verifiability, ConceptChunk
physLib,
  ConceptChunk
understandability, ConceptChunk
reusability, ConceptChunk
maintainability, ConceptChunk
portability,
  ConceptChunk
performance, ConceptChunk
program, ConceptChunk
errMsg, ConceptChunk
accuracy, ConceptChunk
reliability]

c, errMsg, physLib, program :: ConceptChunk

c :: ConceptChunk
c       = String -> NP -> String -> ConceptChunk
dcc String
"c" (String -> NP
pn String
"C") 
  String
"the C programming language"
physLib :: ConceptChunk
physLib = String -> NP -> String -> ConceptChunk
dcc String
"physLib" (String -> NP
cnIES String
"physics library") 
  String
"a programming library which provides functions for modelling physical phenomenon"
program :: ConceptChunk
program = String -> NP -> String -> ConceptChunk
dcc String
"program" (String -> NP
cn' String
"program")
  String
"a series of coded software instructions to control the operation of a computer or other machine"
errMsg :: ConceptChunk
errMsg  = String -> NP -> String -> ConceptChunk
dcc String
"errMsg" (String -> NP
cn' String
"error message") 
  String
"a message that indicates an incorrect instruction has been given, or that there is an error resulting from faulty software"

-- * Non-functional Requirements 

accuracy, correctness, maintainability, performance, performanceSpd, portability,
  reliability, reusability, understandability, verifiability :: ConceptChunk

qualOfBeing :: String -> String
qualOfBeing :: String -> String
qualOfBeing String
s = String
"the quality or state of being" String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
s
  
accuracy :: ConceptChunk
accuracy          = String -> NP -> String -> ConceptChunk
dcc String
"accuracy"          (String -> NP
nounPhraseSP String
"accuracy")
  (String -> ConceptChunk) -> String -> ConceptChunk
forall a b. (a -> b) -> a -> b
$ String -> String
qualOfBeing String
"correct or precise"

correctness :: ConceptChunk
correctness       = String -> NP -> String -> ConceptChunk
dcc String
"correctness"       (String -> NP
nounPhraseSP String
"correctness")
  (String -> ConceptChunk) -> String -> ConceptChunk
forall a b. (a -> b) -> a -> b
$ String -> String
qualOfBeing String
"free from error"
  
maintainability :: ConceptChunk
maintainability   = String -> NP -> String -> ConceptChunk
dcc String
"maintainability"   (String -> NP
nounPhraseSP String
"maintainability")
  String
"the probability of performing a successful repair action within a given time"

performance :: ConceptChunk
performance       = String -> NP -> String -> ConceptChunk
dcc String
"performance"       (String -> NP
nounPhraseSP String
"performance")
  String
"the action or process of carrying out or accomplishing an action, task, or function"

performanceSpd :: ConceptChunk
performanceSpd    = String -> NP -> String -> ConceptChunk
dcc String
"performanceSpd"    (String -> NP
cn' String
"performance speed")
  String
"the action or process of carrying out or accomplishing an action, task, or function quickly"
 
portability :: ConceptChunk
portability       = String -> NP -> String -> ConceptChunk
dcc String
"portability"       (String -> NP
nounPhraseSP String
"portability")
  String
"the ability of software to be transferred from one machine or system to another"

reliability :: ConceptChunk
reliability       = String -> NP -> String -> ConceptChunk
dcc String
"reliability"       (String -> NP
nounPhraseSP String
"reliability")
  (String
"the degree to which the result of a measurement, calculation," String -> String -> String
forall a. [a] -> [a] -> [a]
++
  String
"or specification can be depended on to be accurate")

reusability :: ConceptChunk
reusability       = String -> NP -> String -> ConceptChunk
dcc String
"reusability"       (String -> NP
nounPhraseSP String
"reusability")
  String
"the use of existing assets in some form within the software product development process"

understandability :: ConceptChunk
understandability = String -> NP -> String -> ConceptChunk
dcc String
"understandability" (String -> NP
nounPhraseSP String
"understandability")
  (String -> ConceptChunk) -> String -> ConceptChunk
forall a b. (a -> b) -> a -> b
$ String -> String
qualOfBeing String
"understandable"

verifiability :: ConceptChunk
verifiability     = String -> NP -> String -> ConceptChunk
dcc String
"verifiability"     (String -> NP
nounPhraseSP String
"verifiability")
  (String -> ConceptChunk) -> String -> ConceptChunk
forall a b. (a -> b) -> a -> b
$ String -> String
qualOfBeing String
"capable of being verified, confirmed, or substantiated"

-- * Module Concepts

-- MODULES Concepts (Maybe move to D.D.C.Software.Modules ?)

--FIXME: "hiding" is not a noun.
hwHiding :: ConceptChunk
hwHiding :: ConceptChunk
hwHiding = String -> NP -> String -> ConceptChunk
dcc String
"hwHiding" (String -> NP
cn String
"hardware hiding")
  (String
"hides the exact details of the hardware, and provides a uniform interface" String -> String -> String
forall a. [a] -> [a] -> [a]
++
   String
" for the rest of the system to use")

modBehavHiding :: ConceptChunk
modBehavHiding :: ConceptChunk
modBehavHiding = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modBehavHiding" (String -> NP
cn String
"behaviour hiding") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"includes programs that provide externally visible behaviour of the", 
   String -> Sentence
S String
"system as specified in the", CI -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase CI
srs, Sentence -> Sentence
sParen (Sentence -> Sentence) -> Sentence -> Sentence
forall a b. (a -> b) -> a -> b
$ CI -> Sentence
forall c. Idea c => c -> Sentence
short CI
srs Sentence -> Sentence -> Sentence
+:+. String -> Sentence
S String
"documents",
   String -> Sentence
S String
"This module serves as a communication layer between the hardware-hiding module",
   String -> Sentence
S String
"and the software decision module. The programs in this module will need",
   String -> Sentence
S String
"to change if there are changes in the", CI -> Sentence
forall c. Idea c => c -> Sentence
short CI
srs])

modControl :: ConceptChunk
modControl :: ConceptChunk
modControl = String -> NP -> String -> ConceptChunk
dcc String
"modControl" (String -> NP
cn' String
"control module") String
"provides the main program"

modSfwrDecision :: ConceptChunk
modSfwrDecision :: ConceptChunk
modSfwrDecision = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modSfwrDecision" (String -> NP
cn' String
"software decision module") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"includes", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
dataStruct Sentence -> Sentence -> Sentence
`S.and_` ConceptChunk -> Sentence
forall n. NamedIdea n => n -> Sentence
plural ConceptChunk
algorithm,
   String -> Sentence
S String
"used in the system that do not provide direct interaction with the user"])

modInputFormat :: ConceptChunk
modInputFormat :: ConceptChunk
modInputFormat = String -> NP -> String -> ConceptChunk
dcc String
"modInputFormat" (String -> NP
cn' String
"input format module")
  String
"converts the input data into the data structure used by the input parameters module"
  
modInputParam :: ConceptChunk
modInputParam :: ConceptChunk
modInputParam = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modInputParam" (String -> NP
cn' String
"input parameter module") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"stores the parameters needed for the program, including" Sentence -> Sentence -> Sentence
+:+. SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List
   [String -> Sentence
S String
"material properties", String -> Sentence
S String
"processing conditions", String -> Sentence
S String
"numerical parameters"],
   String -> Sentence
S String
"The values can be read as needed. This module knows how many parameters it stores"])

modInputConstraint :: ConceptChunk
modInputConstraint :: ConceptChunk
modInputConstraint = String -> NP -> String -> ConceptChunk
dcc String
"modInputConstraint" (String -> NP
cn' String
"input constraint module") 
  (String
"defines the constraints on the input data and gives an error if " String -> String -> String
forall a. [a] -> [a] -> [a]
++
   String
"a constraint is violated")

modInputVerif :: ConceptChunk
modInputVerif :: ConceptChunk
modInputVerif = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modInputVerif" (String -> NP
cn' String
"input verification module") ([Sentence] -> Sentence
foldlSent
  [String -> Sentence
S String
"verifies that the", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
inParam, String -> Sentence
S String
"comply with", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
physical Sentence -> Sentence -> Sentence
`S.and_`
   IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
softwareConstraint, String -> Sentence
S String
"Throws an error if a parameter violates a" Sentence -> Sentence -> Sentence
+:+.
   IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
physicalConstraint, String -> Sentence
S String
"Throws a warning if a parameter violates a",
   IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
softwareConstraint])

modDerivedVal :: ConceptChunk
modDerivedVal :: ConceptChunk
modDerivedVal = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modDerivedVal" (String -> NP
cn' String
"derived value module") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"defines the", ConceptChunk -> Sentence
forall n. NamedIdea n => n -> Sentence
plural ConceptChunk
equation, String -> Sentence
S String
"transforming the initial", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
input_,
   String -> Sentence
S String
"into derived", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
quantity])

modInterpolation :: ConceptChunk
modInterpolation :: ConceptChunk
modInterpolation = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modInterpolation" (String -> NP
cn String
"interpolation module") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"provides the", ConceptChunk -> Sentence
forall n. NamedIdea n => n -> Sentence
plural ConceptChunk
equation, String -> Sentence
S String
"that take the", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
plural IdeaDict
inParam Sentence -> Sentence -> Sentence
`S.and_`
   String -> Sentence
S String
"interpolation data" Sentence -> Sentence -> Sentence
`S.and_` String -> Sentence
S String
"return an interpolated value"])

modInterpDatum :: ConceptChunk
modInterpDatum :: ConceptChunk
modInterpDatum = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modInterpDatum" (String -> NP
cn String
"interpolation datum module") ([Sentence] -> Sentence
foldlSent_
  [String -> Sentence
S String
"converts the input interpolation data into the", IdeaDict -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase IdeaDict
dataStruct,
   String -> Sentence
S String
"used by the", ConceptChunk -> Sentence
forall n. NamedIdea n => n -> Sentence
phrase ConceptChunk
modInterpolation])

{-- Concept Chunks for Modules  --}

modSeqServ :: ConceptChunk
modSeqServ :: ConceptChunk
modSeqServ = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modSeqServ" (String -> NP
cn' String
"sequence data structure")
  (String -> Sentence
S String
"Provides array manipulation operations, such as" Sentence -> Sentence -> Sentence
+:+ SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List
   [String -> Sentence
S String
"building an array", String -> Sentence
S String
"accessing a specific entry", String -> Sentence
S String
"slicing an array"])

modLinkedServ :: ConceptChunk
modLinkedServ :: ConceptChunk
modLinkedServ = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modLinkedServ" (String -> NP
cn' String
"linked data structure")
  (String -> Sentence
S String
"Provides tree manipulation operations, such as" Sentence -> Sentence -> Sentence
+:+ SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List
   [String -> Sentence
S String
"building a tree", String -> Sentence
S String
"accessing a specific entry"])

modAssocServ :: ConceptChunk
modAssocServ :: ConceptChunk
modAssocServ = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modAssocServ" (String -> NP
cn' String
"associative data structure")
  (String -> Sentence
S String
"Provides operations on hash tables, such as" Sentence -> Sentence -> Sentence
+:+ SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List
   [String -> Sentence
S String
"building a hash table", String -> Sentence
S String
"accessing a specific entry"])

modVectorServ :: ConceptChunk
modVectorServ :: ConceptChunk
modVectorServ = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modVectorServ" (String -> NP
cn' String
"vector")
  (String -> Sentence
S String
"Provides vector operations such as" Sentence -> Sentence -> Sentence
+:+ SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List [String -> Sentence
S String
"addition",
   String -> Sentence
S String
"scalar and vector multiplication", String -> Sentence
S String
"dot and cross products", String -> Sentence
S String
"rotations"])
  
modPlotDesc :: ConceptChunk
modPlotDesc :: ConceptChunk
modPlotDesc = String -> NP -> String -> ConceptChunk
dcc String
"modPlotDesc" (String -> NP
cn' String
"plotting") String
"provides a plot function"

modOutputfDescFun :: Sentence -> ConceptChunk
modOutputfDescFun :: Sentence -> ConceptChunk
modOutputfDescFun Sentence
desc = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modOutputfDescFun" (String -> NP
cn' String
"output format")
  (String -> Sentence
S String
"outputs the results of the calculations, including the" Sentence -> Sentence -> Sentence
+:+ Sentence
desc)

-- ODE Solver Module
modOdeDesc :: ConceptChunk
modOdeDesc :: ConceptChunk
modOdeDesc = String -> NP -> Sentence -> ConceptChunk
dccWDS String
"modOdeDesc" (String -> NP
nounPhraseSP String
"ODE solver")
  (String -> Sentence
S String
"provides solvers that take the" Sentence -> Sentence -> Sentence
+:+ SepType -> FoldType -> [Sentence] -> Sentence
foldlList SepType
Comma FoldType
List
   [String -> Sentence
S String
"governing equation", String -> Sentence
S String
"initial conditions", String -> Sentence
S String
"numerical parameters"] Sentence -> Sentence -> Sentence
`S.and_`
   String -> Sentence
S String
"solve them")