Safe Haskell	Safe-Inferred
Language	Haskell2010

Drasil.DocLang

Contents

Document Language
- SRS
  - Types
  - Functions
- Notebook
  - Types
  - Functions
Subsection Functions
Document Extraction Function
References

Description

Re-export document language types and functions for easy use in other packages.

Synopsis

type SRSDecl = [DocSection]
data DocSection
- = TableOfContents
- | RefSec RefSec
- | IntroSec IntroSec
- | StkhldrSec StkhldrSec
- | GSDSec GSDSec
- | SSDSec SSDSec
- | ReqrmntSec ReqrmntSec
- | LCsSec
- | UCsSec
- | TraceabilitySec TraceabilitySec
- | AuxConstntSec AuxConstntSec
- | Bibliography
- | AppndxSec AppndxSec
- | OffShelfSolnsSec OffShelfSolnsSec
newtype ReqrmntSec = ReqsProg [ReqsSub]
data ReqsSub where
- FReqsSub :: Sentence -> [LabelledContent] -> ReqsSub
- FReqsSub' :: [LabelledContent] -> ReqsSub
- NonFReqsSub :: ReqsSub
data PDSub where
- TermsAndDefs :: Concept c => Maybe Sentence -> [c] -> PDSub
- PhySysDesc :: Idea a => a -> [Sentence] -> LabelledContent -> [Contents] -> PDSub
- Goals :: [Sentence] -> PDSub
data ProblemDescription where
- PDProg :: Sentence -> [Section] -> [PDSub] -> ProblemDescription
newtype SSDSec = SSDProg [SSDSub]
data SSDSub where
- SSDProblem :: ProblemDescription -> SSDSub
- SSDSolChSpec :: SolChSpec -> SSDSub
data SCSSub where
- Assumptions :: SCSSub
- TMs :: [Sentence] -> Fields -> SCSSub
- GDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub
- DDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub
- IMs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub
- Constraints :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => Sentence -> [c] -> SCSSub
- CorrSolnPpties :: (Quantity c, Constrained c) => [c] -> [Contents] -> SCSSub
data SolChSpec where
- SCSProg :: [SCSSub] -> SolChSpec
newtype AppndxSec = AppndxProg [Contents]
data AuxConstntSec = AuxConsProg CI [ConstQDef]
data DerivationDisplay
- = ShowDerivation
- | HideDerivation
data Emphasis
- = Bold
- | Italics
newtype OffShelfSolnsSec = OffShelfSolnsProg [Contents]
newtype GSDSec = GSDProg [GSDSub]
data GSDSub where
- SysCntxt :: [Contents] -> GSDSub
- UsrChars :: [Contents] -> GSDSub
- SystCons :: [Contents] -> [Section] -> GSDSub
data IntroSec = IntroProg Sentence Sentence [IntroSub]
data IntroSub where
- IPurpose :: [Sentence] -> IntroSub
- IScope :: Sentence -> IntroSub
- IChar :: [Sentence] -> [Sentence] -> [Sentence] -> IntroSub
- IOrgSec :: CI -> Section -> Sentence -> IntroSub
data LFunc where
- Term :: LFunc
- Defn :: LFunc
- TermExcept :: [DefinedQuantityDict] -> LFunc
- DefnExcept :: [DefinedQuantityDict] -> LFunc
- TAD :: LFunc
data Literature
- = Lit Topic
- | Doc' Topic
- | Manual Topic
data RefSec = RefProg Contents [RefTab]
data RefTab where
- TUnits :: RefTab
- TUnits' :: [TUIntro] -> ([UnitDefn] -> LabelledContent) -> RefTab
- TSymb :: [TSIntro] -> RefTab
- TSymb' :: LFunc -> [TSIntro] -> RefTab
- TAandA :: RefTab
newtype StkhldrSec = StkhldrProg [StkhldrSub]
data StkhldrSub where
- Client :: CI -> Sentence -> StkhldrSub
- Cstmr :: CI -> StkhldrSub
data TConvention
- = Vector Emphasis
- | Verb Sentence
newtype TraceabilitySec = TraceabilityProg [TraceConfig]
data TSIntro
- = TypogConvention [TConvention]
- | SymbOrder
- | SymbConvention [Literature]
- | TSPurpose
- | VectorUnits
data TUIntro
- = System
- | Derived
- | TUPurpose
mkDoc :: SRSDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document
fillTraceSI :: SRSDecl -> SystemInformation -> SystemInformation
fillcdbSRS :: SRSDecl -> SystemInformation -> SystemInformation
findAllRefs :: Section -> [Reference]
type LsnDecl = [LsnChapter]
data LsnChapter
- = Intro Intro
- | LearnObj LearnObj
- | Review Review
- | CaseProb CaseProb
- | Example Example
- | Smmry Smmry
- | BibSec
- | Apndx Apndx
newtype Intro = IntrodProg [Contents]
newtype LearnObj = LrnObjProg [Contents]
newtype Review = ReviewProg [Contents]
newtype CaseProb = CaseProbProg [Contents]
newtype Example = ExampleProg [Contents]
newtype Smmry = SmmryProg [Contents]
newtype Apndx = ApndxProg [Contents]
mkNb :: LsnDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document
data Field
- = Label
- | Symbol
- | Units
- | DefiningEquation
- | Description Verbosity InclUnits
- | Input
- | Output
- | InConstraints
- | OutConstraints
- | Notes
- | Source
- | RefBy
type Fields = [Field]
data InclUnits = IncludeUnits
data Verbosity
- = Verbose
- | Succinct
ddefn :: Fields -> SystemInformation -> DataDefinition -> LabelledContent
mkGraphInfo :: SystemInformation -> GraphInfo
traceyGraphGetRefs :: String -> [Reference]
traceMatStandard :: SystemInformation -> [TraceConfig]
traceMatOtherReq :: SystemInformation -> TraceConfig
generateTraceMap :: [DocSection] -> TraceMap
tableOfConstants :: [ConstQDef] -> LabelledContent
purpDoc :: CI -> Verbosity -> [Sentence]
intro :: Contents
emptySectSentPlu :: NamedIdea n => [n] -> Sentence
emptySectSentSing :: NamedIdea n => [n] -> Sentence
tsymb :: [TSIntro] -> RefTab
tsymb'' :: [TSIntro] -> LFunc -> RefTab
unitTableRef :: Reference
tunit :: [TUIntro] -> RefTab
tunit' :: [TUIntro] -> RefTab
tunitNone :: [TUIntro] -> RefTab
inReq :: Sentence -> ConceptInstance
inTable :: (Quantity i, MayHaveUnit i) => [i] -> LabelledContent
mkInputPropsTable :: (Quantity i, MayHaveUnit i, HasShortName r, Referable r) => [i] -> r -> LabelledContent
mkQRTuple :: (HasOutput i, HasShortName i, Referable i) => [i] -> [(QuantityDict, Sentence)]
mkQRTupleRef :: (Quantity i, MayHaveUnit i, HasShortName r, Referable r) => [i] -> [r] -> [(QuantityDict, Sentence)]
mkValsSourceTable :: (Quantity i, MayHaveUnit i) => [(i, Sentence)] -> String -> Sentence -> LabelledContent
reqInputsRef :: Reference
mkMaintainableNFR :: String -> Integer -> String -> ConceptInstance
mkPortableNFR :: String -> [String] -> String -> ConceptInstance
mkCorrectNFR :: String -> String -> ConceptInstance
mkVerifiableNFR :: String -> String -> ConceptInstance
mkUnderstandableNFR :: String -> String -> ConceptInstance
mkReusableNFR :: String -> String -> ConceptInstance
mkSecurityNFR :: String -> String -> ConceptInstance
auxSpecSent :: Sentence
termDefnF' :: Maybe Sentence -> [Contents] -> Section
inDataConstTbl :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => [c] -> LabelledContent
outDataConstTbl :: (Quantity c, Constrained c) => [c] -> LabelledContent
getDocDesc :: DocDesc -> [Sentence]
egetDocDesc :: DocDesc -> [ModelExpr]
secRefs :: [Reference]

Document Language

SRS

For generating Software Requirements Specifications.

Types

type SRSDecl = [DocSection] Source #

A Software Requirements Specification Declaration is made up of all necessary sections (DocSections).

data DocSection Source #

Contains all the different sections needed for a full SRS (SRSDecl).

Constructors

TableOfContents	Table of Contents
RefSec RefSec	Reference.
IntroSec IntroSec	Introduction.
StkhldrSec StkhldrSec	Stakeholders.
GSDSec GSDSec	General System Description.
SSDSec SSDSec	Specific System Description.
ReqrmntSec ReqrmntSec	Requirements.
LCsSec	Likely Changes.
UCsSec	Unlikely Changes.
TraceabilitySec TraceabilitySec	Traceability.
AuxConstntSec AuxConstntSec	Auxiliary Constants.
Bibliography	Bibliography.
AppndxSec AppndxSec	Appendix.
OffShelfSolnsSec OffShelfSolnsSec	Off the Shelf Solutions.

newtype ReqrmntSec Source #

Requirements section (wraps ReqsSub subsections).

Constructors

ReqsProg [ReqsSub]

data ReqsSub where Source #

Requirements subsections.

Constructors

FReqsSub :: Sentence -> [LabelledContent] -> ReqsSub	Functional requirements. `LabelledContent` for tables (includes input values).
FReqsSub' :: [LabelledContent] -> ReqsSub	Functional requirements. `LabelledContent` for tables (no input values).
NonFReqsSub :: ReqsSub	Non-Functional requirements.

data PDSub where Source #

Problem Description subsections.

Constructors

TermsAndDefs :: Concept c => Maybe Sentence -> [c] -> PDSub	Terms and Definitions.
PhySysDesc :: Idea a => a -> [Sentence] -> LabelledContent -> [Contents] -> PDSub	Physical System Description.
Goals :: [Sentence] -> PDSub	Goals.

data ProblemDescription where Source #

Problem Description section.

Constructors

PDProg :: Sentence -> [Section] -> [PDSub] -> ProblemDescription

newtype SSDSec Source #

Specific System Description section (wraps SSDSub subsections).

Constructors

SSDProg [SSDSub]

data SSDSub where Source #

Specific System Description subsections.

Constructors

SSDProblem :: ProblemDescription -> SSDSub	Problem description.
SSDSolChSpec :: SolChSpec -> SSDSub	Solution characteristics.

data SCSSub where Source #

Solution Characteristics Specification subsections.

Constructors

Assumptions :: SCSSub	Assumptions.
TMs :: [Sentence] -> Fields -> SCSSub	Theory models.
GDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub	General definitions.
DDs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub	Data definitions.
IMs :: [Sentence] -> Fields -> DerivationDisplay -> SCSSub	Instance models.
Constraints :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => Sentence -> [c] -> SCSSub	Constraints.
CorrSolnPpties :: (Quantity c, Constrained c) => [c] -> [Contents] -> SCSSub	Properties of a correct solution.

data SolChSpec where Source #

Solution Characteristics Specification section (wraps SCSSub subsections).

Constructors

SCSProg :: [SCSSub] -> SolChSpec

newtype AppndxSec Source #

Appendix section.

Constructors

AppndxProg [Contents]

data AuxConstntSec Source #

Values of Auxiliary Constants section.

Constructors

AuxConsProg CI [ConstQDef]

data DerivationDisplay Source #

Choose whether to show or hide the derivation of an expression.

Constructors

ShowDerivation
HideDerivation

data Emphasis Source #

How to handle emphasis of words.

Constructors

Bold
Italics

Instances

Instances details

Show Emphasis Source #
Instance details Defined in Drasil.DocumentLanguage.Core Methods showsPrec :: Int -> Emphasis -> ShowS # show :: Emphasis -> String # showList :: [Emphasis] -> ShowS #

newtype OffShelfSolnsSec Source #

Off-The-Shelf Solutions section.

Constructors

OffShelfSolnsProg [Contents]

newtype GSDSec Source #

General System Description section (wraps GSDSub subsections).

Constructors

GSDProg [GSDSub]

data GSDSub where Source #

General System Description subsections.

Constructors

SysCntxt :: [Contents] -> GSDSub	System context.
UsrChars :: [Contents] -> GSDSub	User characteristics.
SystCons :: [Contents] -> [Section] -> GSDSub	System constraints.

data IntroSec Source #

Introduction section. Contents are top level followed by a list of subsections.

Constructors

IntroProg Sentence Sentence [IntroSub]

Temporary, will be modified once we've figured out more about the section.

data IntroSub where Source #

Introduction subsections.

Constructors

IPurpose :: [Sentence] -> IntroSub	Describes purpose of the system.
IScope :: Sentence -> IntroSub	Describes scope of the system.
IChar :: [Sentence] -> [Sentence] -> [Sentence] -> IntroSub	Describes characteristics of the system.
IOrgSec :: CI -> Section -> Sentence -> IntroSub	Organises the section.

data LFunc where Source #

Lens (lookup) functions (currently for TSymb).

Constructors

Term :: LFunc
Defn :: LFunc
TermExcept :: [DefinedQuantityDict] -> LFunc
DefnExcept :: [DefinedQuantityDict] -> LFunc
TAD
Fields :: LFunc Term and Definition.

data Literature Source #

Types of literature.

Constructors

Lit Topic	Literature (with a Topic).
Doc' Topic	Existing documentation for (plural version of topic).
Manual Topic	Manual.

data RefSec Source #

Reference section. Contents are top level followed by a list of subsections.

Constructors

RefProg Contents [RefTab]

data RefTab where Source #

Reference subsections (tables) made out of units or symbols (can be customized).

Constructors

TUnits :: RefTab	Default table of units.
TUnits' :: [TUIntro] -> ([UnitDefn] -> LabelledContent) -> RefTab	Customized introduction.
TSymb :: [TSIntro] -> RefTab	Adds an introduction for a table of symbols.
TSymb' :: LFunc -> [TSIntro] -> RefTab	Allows Lens functions in addition to an introduction for a table of symbols.
TAandA :: RefTab	Default.

newtype StkhldrSec Source #

Stakeholders section (wraps stakeholders subsections StkhldrSub).

Constructors

StkhldrProg [StkhldrSub]

data StkhldrSub where Source #

Stakeholders subsections.

Constructors

Client :: CI -> Sentence -> StkhldrSub	May have a client.
Cstmr :: CI -> StkhldrSub	May have a customer.

data TConvention Source #

Possible typographic conventions.

Constructors

Vector Emphasis	How vectors are emphasized.
Verb Sentence	Verbatim for specialized conventions.

newtype TraceabilitySec Source #

Traceability Matices and Graphs section. Contains configurations (TraceConfig).

Constructors

TraceabilityProg [TraceConfig]

data TSIntro Source #

For creating a table of symbols introduction

Constructors

TypogConvention [TConvention]	Typographic conventions used.
SymbOrder	Symbol ordering (defaults to alphabetical).
SymbConvention [Literature]	Symbol conventions match specified literature.
TSPurpose	Purpose of the Table of Symbols.
VectorUnits	Definition of vector components.

data TUIntro Source #

For creating the table of units introduction.

Constructors

System	System of units (defaults to SI).
Derived	Sentence about derived units being used alongside SI.
TUPurpose	Purpose of the table of units.

Functions

mkDoc :: SRSDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document Source #

Creates a document from a document description, a title combinator function, and system information.

fillTraceSI :: SRSDecl -> SystemInformation -> SystemInformation Source #

Helper for filling in the traceability matrix and graph information into the system.

fillcdbSRS :: SRSDecl -> SystemInformation -> SystemInformation Source #

Assuming a given ChunkDB with no traces and minimal/no references, fill in for rest of system information. Currently fills in references, traceability matrix information and IdeaDicts.

findAllRefs :: Section -> [Reference] Source #

Recursively find all references in a section (meant for getting at LabelledContent).

Notebook

For generating Jupyter notebook lesson plans.

Types

type LsnDecl = [LsnChapter] Source #

A Lesson Plan notebook declaration is made up of all necessary chapters (LsnChapters).

data LsnChapter Source #

Contains all the different chapters needed for a notebook lesson plan (LsnDecl).

Constructors

Intro Intro
LearnObj LearnObj
Review Review
CaseProb CaseProb
Example Example
Smmry Smmry
BibSec
Apndx Apndx

newtype Intro Source #

Constructors

IntrodProg [Contents]

newtype LearnObj Source #

Constructors

LrnObjProg [Contents]

newtype Review Source #

Constructors

ReviewProg [Contents]

newtype CaseProb Source #

Constructors

CaseProbProg [Contents]

newtype Example Source #

Constructors

ExampleProg [Contents]

newtype Smmry Source #

Constructors

SmmryProg [Contents]

newtype Apndx Source #

Constructors

ApndxProg [Contents]

Functions

mkNb :: LsnDecl -> (IdeaDict -> IdeaDict -> Sentence) -> SystemInformation -> Document Source #

Creates a notebook from a lesson description and system information.

Subsection Functions

Definitions and Models

data Field Source #

Fields that should be displayed in definitions.

Constructors

Label
Symbol
Units
DefiningEquation
Description Verbosity InclUnits
Input
Output
InConstraints
OutConstraints
Notes
Source
RefBy

Instances

Instances details

Show Field Source #	Defines `Field`s as `Space`s.
Instance details Defined in Drasil.DocumentLanguage.Definitions Methods showsPrec :: Int -> Field -> ShowS # show :: Field -> String # showList :: [Field] -> ShowS #

type Fields = [Field] Source #

Synonym for a list of Fields.

data InclUnits Source #

Determines whether to include or ignore units.

Constructors

IncludeUnits

In description field (for other symbols).

data Verbosity Source #

Refers to the verbosity of statements.

Constructors

Verbose	Full Descriptions.
Succinct	Simple Description (do not redefine other symbols).

ddefn :: Fields -> SystemInformation -> DataDefinition -> LabelledContent Source #

Create a data definition using a list of fields, a database of symbols, and a QDefinition (called automatically by SCSSub program).

Traceability

mkGraphInfo :: SystemInformation -> GraphInfo Source #

Extracts traceability graph inforomation from filled-in SystemInformation.

traceyGraphGetRefs :: String -> [Reference] Source #

Create references to traceability graphs given an example name. Primarily used for reference database in examples.

traceMatStandard :: SystemInformation -> [TraceConfig] Source #

Helpers to check if given argument has more than one peice of information

Contains traceability matrix assumptions, other assumptions, refinement, and other requirements.

traceMatOtherReq :: SystemInformation -> TraceConfig Source #

Records other requirements. Converts the SystemInformation into a TraceConfig.

generateTraceMap :: [DocSection] -> TraceMap Source #

Creates a traceability map from document sections.

Auxiliary Constants

tableOfConstants :: [ConstQDef] -> LabelledContent Source #

Helper that gets a table of constants from a QDefinition.

Introduction

purpDoc :: CI -> Verbosity -> [Sentence] Source #

Combines purpDocPara1 and developmentProcessParagraph. Verbosity controls if the developmentProcessParagraph is added or not.

Reference Material

intro :: Contents Source #

Default Reference Material section introduction.

emptySectSentPlu :: NamedIdea n => [n] -> Sentence Source #

Helper for variants of emptySectSent

emptySectSentSing :: NamedIdea n => [n] -> Sentence Source #

Helper for variants of emptySectSent

tsymb :: [TSIntro] -> RefTab Source #

Default is term and given introduction.

Table of symbols constructor.

tsymb'' :: [TSIntro] -> LFunc -> RefTab Source #

Table of symbols constructor. Takes a custom function and introduction.

unitTableRef :: Reference Source #

Makes a reference to the Table of Units.

tunit :: [TUIntro] -> RefTab Source #

Table of units with an SI Name.

Table of units constructors.

tunit' :: [TUIntro] -> RefTab Source #

Table of units with SI name in the description column.

Table of units constructors.

tunitNone :: [TUIntro] -> RefTab Source #

Table of units with SI name in the description column.

Table of units constructors.

Requirements

inReq :: Sentence -> ConceptInstance Source #

Creates a ConceptInstance of input values.

inTable :: (Quantity i, MayHaveUnit i) => [i] -> LabelledContent Source #

Creates a generalized input-value table for the Requirements section.

mkInputPropsTable :: (Quantity i, MayHaveUnit i, HasShortName r, Referable r) => [i] -> r -> LabelledContent Source #

Creates an Input Data Table for use in the Functional Requirments section. Takes a list of wrapped variables and something that is Referable.

mkQRTuple :: (HasOutput i, HasShortName i, Referable i) => [i] -> [(QuantityDict, Sentence)] Source #

mkQRTupleRef :: (Quantity i, MayHaveUnit i, HasShortName r, Referable r) => [i] -> [r] -> [(QuantityDict, Sentence)] Source #

mkValsSourceTable :: (Quantity i, MayHaveUnit i) => [(i, Sentence)] -> String -> Sentence -> LabelledContent Source #

Creates a table for use in the Functional Requirments section. Takes a list of tuples containing variables and sources, a label, and a caption.

reqInputsRef :: Reference Source #

Reference for the Required Inputs table.

mkMaintainableNFR :: String -> Integer -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Maintainability. Takes in a Reference Address (Space), a percent value (Space), and a label (Space).

mkPortableNFR :: String -> [String] -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Portability.

mkCorrectNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Correctness.

mkVerifiableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Verifiability.

mkUnderstandableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Understandability.

mkReusableNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Reusability.

mkSecurityNFR :: String -> String -> ConceptInstance Source #

Common Non-Functional Requirement for Security.

Specific System Description

auxSpecSent :: Sentence Source #

General Sentence that describes some auxiliary specifications of the system.

termDefnF' :: Maybe Sentence -> [Contents] -> Section Source #

Similar to termDefnF, except does not take definitions from the list of terms.

inDataConstTbl :: (HasUncertainty c, Quantity c, Constrained c, HasReasVal c, MayHaveUnit c) => [c] -> LabelledContent Source #

Creates the input Data Constraints Table.

outDataConstTbl :: (Quantity c, Constrained c) => [c] -> LabelledContent Source #

Creates the output Data Constraints Table.

Document Extraction Function

getDocDesc :: DocDesc -> [Sentence] Source #

Extracts Sentences from a document description.

egetDocDesc :: DocDesc -> [ModelExpr] Source #

Extracts expressions from the document description (DocDesc) and default DLPlate.

References

secRefs :: [Reference] Source #

All section references used in creating a Software Requirements Specification (SRS).