drasil-lang-0.1.60.0: A framework for code and document generation for scientific software - Language SubPackage
Safe HaskellSafe-Inferred
LanguageHaskell2010

Language.Drasil.Document

Description

Document Description Language.

Synopsis

List Creation Functions

enumBullet :: Reference -> [Sentence] -> LabelledContent Source #

Creates a bulleted list.

enumBulletU :: [Sentence] -> Contents Source #

Same as enumBullet but unlabelled.

enumSimple :: Reference -> Integer -> Sentence -> [Sentence] -> LabelledContent Source #

Currently Unused. Creates a simple bulleted list that labels things with a title and number:

  • lb - Reference,
  • s - start index for the enumeration,
  • t - title of the list,
  • l - list to be enumerated.

For example, if we want to create a list of data definitions, we could call the function as follows:

enumSimple _ 2 (S "DD") [def1, def2, ...]

And the resulting LabelledContent would be rendered as:

  • DD2: def1
  • DD3: def2
  • DD4: def3 ...

enumSimpleU :: Integer -> Sentence -> [Sentence] -> Contents Source #

Same as enumSimple but unlabelled.

mkEnumSimpleD :: (Referable c, HasShortName c, Definition c) => [c] -> [Contents] Source #

Convenience function for transforming referable concepts into a bulleted list. Used in drasil-docLang in making the assumptions, goals, and requirements sections. Output is of the kind Concept Name: definition of concept.

Displaying Expressions

lbldExpr :: ModelExpr -> Reference -> LabelledContent Source #

Displays a given expression and attaches a Reference to it.

unlbldExpr :: ModelExpr -> Contents Source #

Same as eqUnR except content is unlabelled (does not attach a Reference).

unlbldCode :: Expr -> Contents Source #

Unlabelled code expression

Folds

foldlSP :: [Sentence] -> Contents Source #

Fold sentences then turns into content using foldlSent.

data Contents Source #

Contents may be labelled or unlabelled.

Instances

Instances details
HasContents Contents Source #

Access the RawContent within Contents.

Instance details

Defined in Language.Drasil.Document.Core

data ListType Source #

Denotes the different possible types that can be used as a list.

Constructors

Bullet [(ItemType, Maybe String)]

Bulleted list.

Numeric [(ItemType, Maybe String)]

Enumerated list.

Simple [ListTuple]

Simple list with items denoted by :. Renders as "Title: Item"

Desc [ListTuple]

Descriptive list, renders as "Title: Item" (see ListTuple).

Definitions [ListTuple]

Renders a list of "Title is the Item".

data ItemType Source #

Denotes how something should behave in a list (ListType).

Constructors

Flat Sentence

Standard singular item.

Nested Header ListType

Nest a list (ListType) as an item.

data RawContent Source #

Types of layout objects we deal with explicitly.

Constructors

Table [Sentence] [[Sentence]] Title Bool

table has: header-row, data(rows), label/caption, and a bool that determines whether or not to show label.

Paragraph Sentence

Paragraphs are just sentences.

EqnBlock ModelExpr

Block of Equations holds an expression.

DerivBlock Sentence [RawContent]

Grants the ability to label a group of RawContent.

Enumeration ListType

For enumerated lists.

Defini [(Identifier, [Contents])]

Defines something with a type, identifier, and Contents.

Figure Lbl Filepath MaxWidthPercent HasCaption

For creating figures in a document includes whether the figure has a caption.

Bib BibRef

Grants the ability to reference something.

Graph [(Sentence, Sentence)] (Maybe Width) (Maybe Height) Lbl

Contain a graph with coordinates (Sentences), maybe a width and height, and a label (Sentence).

CodeBlock Expr

Block for codes

type ListTuple Source #

Arguments

 = (Title, ItemType, Maybe String)

Formats as Title: Item. For use in lists.

type MaxWidthPercent = Float Source #

MaxWidthPercent should be kept in the range 1-100. Values outside this range may have unexpected results. Used for specifying max figure width as pagewidth*MaxWidthPercent/100.

class HasContents c where Source #

Members of this class must have RawContent.

Methods

accessContents :: Lens' c RawContent Source #

Provides a Lens to the RawContent.

data LabelledContent Source #

Contains a Reference and RawContent.

Constructors

LblC 

Instances

Instances details
HasChunkRefs LabelledContent Source # 
Instance details

Defined in Language.Drasil.Document.Core

HasUID LabelledContent Source #

Finds UID of the LabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

Methods

uid :: Getter LabelledContent UID #

HasContents LabelledContent Source #

Access the RawContent within the LabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

HasRefAddress LabelledContent Source #

Finds the reference address contained in the Reference of LabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

Referable LabelledContent Source #

Finds the reference information of LabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

HasShortName LabelledContent Source #

Find the shortname of the reference address used for the LabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

Eq LabelledContent Source #

LabelledContents are equal if their reference UIDs are equal.

Instance details

Defined in Language.Drasil.Document.Core

newtype UnlabelledContent Source #

Only contains RawContent.

Constructors

UnlblC 

Fields

Instances

Instances details
HasContents UnlabelledContent Source #

Access the RawContent within the UnlabelledContent.

Instance details

Defined in Language.Drasil.Document.Core

data HasCaption Source #

Indicates whether a figure has a caption or not.

Constructors

NoCaption 
WithCaption 

Instances

Instances details
Eq HasCaption Source # 
Instance details

Defined in Language.Drasil.Document.Core

type Lbl Source #

Arguments

 = Sentence

Label.

Type

data DecRef Source #

For holding a Reference that is decorated with extra information (ex. page numbers, equation sources, etc.).

Constructors

DR 

Fields

Instances

Instances details
HasChunkRefs DecRef Source # 
Instance details

Defined in Language.Drasil.Document.DecoratedReference

Methods

chunkRefs :: DecRef -> Set UID #

HasUID DecRef Source #

Finds the UID of a Reference.

Instance details

Defined in Language.Drasil.Document.DecoratedReference

Methods

uid :: Getter DecRef UID #

HasRefAddress DecRef Source #

Finds the reference address contained in a Reference (through a LblType).

Instance details

Defined in Language.Drasil.Document.DecoratedReference

HasShortName DecRef Source #

Finds the shortname of the reference address used for the Reference.

Instance details

Defined in Language.Drasil.Document.DecoratedReference

Eq DecRef Source #

Equal if UIDs are equal.

Instance details

Defined in Language.Drasil.Document.DecoratedReference

Methods

(==) :: DecRef -> DecRef -> Bool #

(/=) :: DecRef -> DecRef -> Bool #

Class

class HasDecRef c where Source #

A class that contains a list of decorated references (DecRefs).

Methods

getDecRefs :: Lens' c [DecRef] Source #

Provides a Lens to the DecRefs.

Constructors

dRef :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> DecRef Source #

Same as ref, but for DecRef instead of Reference.

dRefInfo :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> RefInfo -> DecRef Source #

For creating a decorated reference (DecRef) with extra reference information (RefInfo).

sentToExp :: Sentence -> [ModelExpr] Source #

Extracts all ModelExprs mentioned in a Sentence.

extractMExprs :: HasContents a => a -> [ModelExpr] Source #

Extracts ModelExprs from something that HasContents.

extractSents :: HasContents a => a -> [Sentence] Source #

Extracts Sentences from something that HasContents.

extractSents' :: HasContents a => [a] -> [Sentence] Source #

Extracts Sentences from a list of Contents.

extractChRefs :: HasContents a => [a] -> Set UID Source #

Extracts all referenced UIDs from things that have RawContents.

getSec :: Section -> [Sentence] Source #

Extracts Sentences from a Section.

extractSectionsBib :: ChunkDB -> [Section] -> BibRef Source #

Extract bibliography entries from generated sections. This version extracts from fully expanded Sections, capturing citations that are only created during document generation (like those in orgOfDocIntro).

resolveBibliography :: ChunkDB -> Set UID -> [Citation] Source #

Given a ChunkDB and a set of UIDs, looks up the corresponding Citations and returns them sorted by author, year, and title.

FIXME: This function assumes that all UIDs in the set correspond to Citations in the database. If a UID does not correspond to a Citation, it is simply ignored. This should rather rely on a set of 'UIDRef Citation's.

Type

data Reference Source #

A Reference contains the identifier (UID), a reference address (LblType), a human-readable shortname (ShortName), and any extra information about the reference (RefInfo).

Instances

Instances details
HasChunkRefs Reference Source # 
Instance details

Defined in Language.Drasil.Document.Reference

Methods

chunkRefs :: Reference -> Set UID #

HasUID Reference Source #

Finds the UID of a Reference.

Instance details

Defined in Language.Drasil.Document.Reference

Methods

uid :: Getter Reference UID #

HasRefAddress Reference Source #

Finds the reference address contained in a Reference (through a LblType).

Instance details

Defined in Language.Drasil.Document.Reference

HasShortName Reference Source #

Finds the shortname of the reference address used for the Reference.

Instance details

Defined in Language.Drasil.Document.Reference

Eq Reference Source #

Equal if UIDs are equal.

Instance details

Defined in Language.Drasil.Document.Reference

Class

class HasReference c where Source #

A class that contains a list of References.

Methods

getReferences :: Lens' c [Reference] Source #

Provides a Lens to the References.

Constructors

ref :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> Reference Source #

Projector function that creates a Reference from something Referable.

refS :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> Sentence Source #

Takes the reference UID and wraps it into a Sentence.

namedRef :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> Sentence -> Sentence Source #

Takes a Reference with a name to be displayed and wraps it into a Sentence. Does not overwrite the shortname contained in the reference, but will only display as the given Sentence.

complexRef :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> RefInfo -> Sentence Source #

Takes a Reference with additional display info. Uses the internal shortname for its display name.

namedComplexRef :: (IsChunk r, HasRefAddress r, HasShortName r) => r -> Sentence -> RefInfo -> Sentence Source #

Takes a Reference with a name to be displayed and any additional information and wraps it into a Sentence. Does not overwrite the shortname contained in the reference, but will only display as the given Sentence along with the given RefInfo.

section :: Sentence -> [Contents] -> [Section] -> Reference -> Section Source #

Smart constructor for creating Sections with a title (Sentence), introductory contents (ie. paragraphs, tables, etc.), a list of subsections, and a shortname (Reference).

fig :: Lbl -> Filepath -> RawContent Source #

Figure smart constructor with a Lbl and a Filepath. Assumes 100% of page width as max width. Defaults to WithCaption.

figNoCap :: Lbl -> Filepath -> RawContent Source #

Figure smart constructor without a caption.

figWithWidth :: Lbl -> Filepath -> MaxWidthPercent -> RawContent Source #

Figure smart constructor that allows for customized max widths. Defaults to WithCaption.

figNoCapWithWidth :: Lbl -> Filepath -> MaxWidthPercent -> RawContent Source #

Figure smart constructor with customized max widths and no caption.

data Section Source #

Sections have a title (Sentence), a list of contents (SecCons) and a shortname (Reference).

Constructors

Section 

Fields

Instances

Instances details
HasChunkRefs Section Source # 
Instance details

Defined in Language.Drasil.Document.Sections

Methods

chunkRefs :: Section -> Set UID #

HasUID Section Source #

Finds the UID of a Section.

Instance details

Defined in Language.Drasil.Document.Sections

Methods

uid :: Getter Section UID #

HasRefAddress Section Source #

Finds the reference address of a Section.

Instance details

Defined in Language.Drasil.Document.Sections

Referable Section Source #

Finds the reference information of a Section.

Instance details

Defined in Language.Drasil.Document.Sections

HasShortName Section Source #

Finds the short name of a Section.

Instance details

Defined in Language.Drasil.Document.Sections

Eq Section Source #

Sections are equal if UIDs are equal.

Instance details

Defined in Language.Drasil.Document.Sections

Methods

(==) :: Section -> Section -> Bool #

(/=) :: Section -> Section -> Bool #

data SecCons Source #

Section Contents are split into subsections or contents, where contents are standard layout objects (see Contents).

Constructors

Sub Section 
Con Contents 

llcc :: UID -> LblType -> ShortName -> RawContent -> LabelledContent Source #

Smart constructor for labelled content chunks. Now builds a Reference using the provided UID instead of extracting it from the Reference.

llccFig :: String -> RawContent -> LabelledContent Source #

Helper for creating labelled content with a figure reference.

llccTab :: String -> RawContent -> LabelledContent Source #

Helper for creating labelled content with a table reference.

llccEqn :: String -> RawContent -> LabelledContent Source #

Helper for creating labelled content with an equation reference.

llccFig' :: UID -> RawContent -> LabelledContent Source #

Helper for creating labelled content with a UID-based figure reference.

llccTab' :: UID -> RawContent -> LabelledContent Source #

Helper for creating labelled content with a UID-based table reference.

llccEqn' :: UID -> RawContent -> LabelledContent Source #

Helper for creating labelled content with a UID-based equation reference.

ulcc :: RawContent -> UnlabelledContent Source #

Smart constructor for unlabelled content chunks (no Reference).

data Document Source #

A Document has a Title (Sentence), Author(s) (Sentence), and Sections which hold the contents of the document.

mkParagraph :: Sentence -> Contents Source #

Smart constructor that wraps UnlabelledContent into Contents.

mkFig :: Reference -> RawContent -> Contents Source #

Smart constructor that wraps LabelledContent into Contents. Takes a Reference to extract UID, LblType, and ShortName for the labelled content.

mkRawLC :: RawContent -> Reference -> LabelledContent Source #

Smart constructor similar to llcc, but takes in RawContent first. Takes a Reference to extract UID, LblType, and ShortName for the labelled content.

data ShowTableOfContents Source #

Determines whether or not the table of contents appears on the generated artifacts.

Constructors

ToC 
NoToC 

checkToC :: Document -> Document Source #

Manually removes the first section of a document (table of contents section). temp fix for Notebook (see if we need this in notebook later)

makeTabRef :: String -> Reference Source #

Create a reference for a table. Takes in the name of a table (which will also be used for its shortname).

makeFigRef :: String -> Reference Source #

Create a reference for a figure. Takes in the name of a figure (which will also be used for its shortname).

makeSecRef :: String -> Sentence -> Reference Source #

Create a reference for a section. Takes in the name of a section and a shortname for the section.

makeEqnRef :: String -> Reference Source #

Create a reference for a equation. Takes in the name of the equation (which will also be used for its shortname).

makeURI :: String -> String -> ShortName -> Reference Source #

Create a reference for a URI. Takes in a UID (as a String), a reference address, and a shortname.

makeTabRef' :: UID -> Reference Source #

Variants of makeTabRef that takes a UID instead of a String.

makeFigRef' :: UID -> Reference Source #

Variants of makeFigRef that takes a UID instead of a String.

makeSecRef' :: UID -> Sentence -> Reference Source #

Variants of makeSecRef that takes a UID instead of a String.

makeEqnRef' :: UID -> Reference Source #

Variants of makeEqnRef that takes a UID instead of a String.

makeURI' :: UID -> String -> ShortName -> Reference Source #

Variants of makeURI that takes a UID instead of a String.

Reference-related Functions

Attach a Reference and a Sentence in different ways.

chgsStart :: (HasShortName x, Referable x) => x -> Sentence -> Sentence Source #

Output is of the form "reference - sentence".

definedIn :: (Referable r, HasShortName r, DefinesQuantity r) => r -> Sentence Source #

Takes a HasSymbol that is also Referable and outputs as a Sentence: "symbol is defined in reference."

definedIn' :: (Referable r, HasShortName r, DefinesQuantity r) => r -> Sentence -> Sentence Source #

Same as definedIn, but allows for additional information to be appended to the Sentence.

definedIn'' :: (Referable r, HasShortName r) => r -> Sentence Source #

Takes a Referable and outputs as a Sentence "defined in reference" (no HasSymbol).

definedIn''' :: (Quantity q, Referable r, HasShortName r) => q -> r -> Sentence Source #

Takes a Symbol and its Reference (does not append a period at the end!). Outputs as "symbol is defined in source".

fromReplace :: (Referable r, HasShortName r, Quantity q) => r -> q -> Sentence Source #

Takes a Referable source and a UnitalChunk and outputs as a Sentence: "From source we can replace symbol:".

fromSource :: (Referable r, HasShortName r) => r -> Sentence Source #

Wraps "from reference" in parentheses.

fromSources :: (Referable r, HasShortName r) => [r] -> Sentence Source #

Similar to fromSource but takes a list of references instead of one.

fmtU :: MayHaveUnit a => Sentence -> a -> Sentence Source #

Takes an amount as a Sentence and appends a unit to it.

follows :: (Referable r, HasShortName r) => Sentence -> r -> Sentence Source #

Appends "following reference" to the end of a Sentence.

makeListRef :: [a] -> Section -> [Sentence] Source #

Takes a list and a Section, then generates a list of that section's reference to match the length of the list.

Sentence-related Functions

See Reference-related Functions as well.

addPercent :: Show a => a -> Sentence Source #

Converts input to a Sentence and appends %.

maybeChanged :: Sentence -> Sentence -> Sentence Source #

Helper functions for making likely change statements. Uses form likelyFrame parameter1 _ parameter2.

maybeExpanded :: Sentence -> Sentence -> Sentence Source #

Helper functions for making likely change statements. Uses form likelyFrame parameter1 _ parameter2.

maybeWOVerb :: Sentence -> Sentence -> Sentence Source #

Helper functions for making likely change statements. Uses form likelyFrame parameter1 _ parameter2.

showingCxnBw :: NamedIdea c => c -> Sentence -> Sentence Source #

Returns the Sentence "(titleize aNamedIdea) Showing the Connections Between contents".

substitute :: (Referable r, HasShortName r, DefinesQuantity r) => [r] -> Sentence Source #

Takes a list of Referables and Symbols and outputs as a Sentence "By substituting symbols, this can be written as:".

typUncr :: (Double, Maybe Int) -> Sentence Source #

Formats typical uncertainty data to be displayed.

underConsidertn :: ConceptChunk -> Sentence Source #

Returns the Sentence "The chunk under consideration is chunkDefinition".

unwrap :: Maybe UnitDefn -> Sentence Source #

Get a unit symbol if there is one.

fterms :: (NamedIdea c, NamedIdea d) => (NP -> NP -> t) -> c -> d -> t Source #

Apply a binary function to the terms of two named ideas, instead of to the named ideas themselves. Ex. fterms compoundPhrase t1 t2 instead of compoundPhrase (t1 ^. term) (t2 ^. term).

eqN :: Int -> Sentence Source #

Prepends the word Equation to an Int.

eqnWSource :: (Referable r, HasShortName r) => ModelExpr -> r -> Sentence Source #

Takes an expression and a Referable and outputs as a Sentence "expression (source)".

List-related Functions

bulletFlat :: [Sentence] -> ListType Source #

Applies Bullet and Flat to a list.

bulletNested :: [Sentence] -> [ListType] -> ListType Source #

Applies Bullets and headers to a Nested ListType. The first argument is the headers of the Nested lists.

itemRefToSent :: String -> Sentence -> Sentence Source #

Makes Sentences from an item and its reference. Takes the title of reference as a String and a Sentence containing the full reference. Wraps the full reference in parenthesis.

makeTMatrix :: Eq a => [Sentence] -> [[a]] -> [a] -> [[Sentence]] Source #

Makes a traceability matrix from a list of row titles, a list of rows of "checked" columns, and a list of columns.

mkEnumAbbrevList :: Integer -> Sentence -> [Sentence] -> [(Sentence, ItemType)] Source #

Zip helper function enumerates abbreviations and zips it with list of ItemType:

  • s - the number from which the enumeration should start from (Integer),
  • t - the title of the list (Sentence),
  • l - the list to be enumerated ([Sentence]).

mkTableFromColumns :: [(Sentence, [Sentence])] -> ([Sentence], [[Sentence]]) Source #

Helper for making a table from a columns.

noRefs :: [ItemType] -> [(ItemType, Maybe String)] Source #

Converts lists of simple ItemTypes into a list which may be used in Contents but is not directly referable.

refineChain :: NamedIdea c => [(c, Section)] -> Sentence Source #

Create a list in the pattern of "The __ are refined to the __". Note: Order matters!

tAndDOnly :: Concept s => s -> ItemType Source #

Helpful combinators for making Sentences into Terminologies with Definitions. Returns of the form: "term - termDefinition".

tAndDWAcc :: Concept s => s -> ItemType Source #

Helpful combinators for making Sentences into Terminologies with Definitions. Returns of the form: "term (abbreviation) - termDefinition".

tAndDWSym :: (Concept s, Quantity a) => s -> a -> ItemType Source #

Helpful combinators for making Sentences into Terminologies with Definitions. Returns of the form: "term (symbol) - termDefinition".

zipSentList :: [[Sentence]] -> [Sentence] -> [[Sentence]] -> [[Sentence]] Source #

Distributes a list of Sentences by prepending individual Sentences once to an existing list of Sentences.

For example:

>>> zipSentList [S "Hi", S "Hey", S "Hi"] [[S "Hello"], [S "World"], [S "Hello", S "World"]]
[[S "Hi", S "Hello"], [S "Hey", S "World"], [S "Hi", S "Hello", S "World"]]