-
Notifications
You must be signed in to change notification settings - Fork 26
Combinator Documentation
Warning: Wiki should not be edited directly. Edit the files in the ./wiki/ folder instead and make a PR.
- Introduction
- Naming
- Sentence-level Combinators
- NounPhrase-level Combinators
- Concept-level Combinators
- Higher-level Combinators
NounPhrases
in Drasil- Notes
The purpose of this page is to help users and contributors easily see the combinators for English that currently exist in Drasil and are available for use. This will also help to keep all of the different combinators organized and to separate them by their English meanings. As brought up in issue #2399, we are trying to encapsulate the knowledge associated with common English combinators as a means to generalize Drasil's language while making readability of the code clearer. So far, we have separated these combinators into four levels:
-
Level 1:
Sentence
level. These combinators can only be used to join twoSentences
, and they do not hold any semantic meaning usable by Drasil. In other words, they are only surface level combinators and are unable to produce a sophisticated idea from two simpler ideas. When joining concepts, these should only be used when the relationship between the phrases is unable to be expressed with any higher-level combinators. -
Level 2:
NounPhrase
level. The combinators listed here are better thanSentence
-level combinators as they can hold information about pluralization and capitalization rules. As a result, Drasil can utilize these combinators in more powerful ways because it can know the rules that govern how an appliedSentence
should look. Because of the nature of theNP
type (having the ability to hold knowledge of singular, plural, capital, and title cases), these combinators can easily replace manySentence
-level combinators and give Drasil more knowledge when recording information. -
Level 3:
NamedIdea
or conceptual level. These combinators are similar to theNounPhrase
combinators, except they are able to hold the semantic meaning of the combinator. These represent a new idea that is built upon multiple simpler ideas, allowing Drasil to grow its knowledge of such ideas. The combinators at this level are ideal and practical for use in Drasil, but they are more difficult to implement. One must be able to see the underlying patterns that are within English, and then apply them using these combinators. For example, something like theofThe
combinator will allow us to contain the knowledge that the first idea is a unique attribute of the second idea. -
Level 4: Things above
NamedIdeas
that are amenable to joining. This is ideal and something to aim for, but a little too early to start incorporating consistently.
The setup for naming combinators is as follows (in order):
- An underscore (
_
) is used when a combinator name would otherwise clash with either Haskell's syntax or any other similarly named functions. Common uses includeof_
,a_
,and_
, etc. The only exceptions to this rule are the following combinators -the_ofThe
,the_ofGive
, andthe_isExpctToHvC
, which are named so because they prepend the word "the" in front of the first term. - An appended
C
denotes that the first word is capitalized (forSentence
types). For example, the only difference betweenthe_ofThe
andthe_ofTheC
is that the first word will be capitalized (in this case, the first "The"). - An appended
T
denotes combinators that are meant for use in titles. All words are either capitalized (forSentence
types) or have some special attribute defined by the following letters in the function definition that determine the title case (forNP
andNamedIdea
types). For example,forT
will capitalize both terms and insert the word "for" between them. Combinators without theT
are still perfectly usable in titles, but this is mainly for when we want to give specific functions to display the title case. - An appended
Gen
denotes the general (or custom) case for a combinator. It often takes functions which can specify the creation of singular, plural, or title cases. An appendedGenGen
takes functions for both singular and plural cases. For example,forGen
takes two functions and two terms, applies the two arguments to the two terms and then insets "for" between them. - Two appended
P
s orS
s often denote the formation of a plural case (commonly used forNP
andNamedIdea
types). For example, the plural case offorPS
makes the first word plural and the second word singular. - Four appended
P
s orS
s denote the formation of the singular and plural cases with the first two letters for the singular case and the last two letters for the plural case (commonly used forNP
andNamedIdea
types). For example, the singular case offorPSPP
makes the first term plural and the second term singular while the plural case becomes the plural of both terms. - Appended
NI
s orNP
s denote the types of arguments the combinator should take. These combinators have the ability to combine aNamedIdea
and aNounPhrase
together respectively and are always appended last to avoid confusion with any appendedP
s orS
s. For example,of_PSNPNI
joins a NounPhrase and a NamedIdea together with the word "of" between them. The plural case then follows theP
andS
(pluralize the first term, keep the second term singular).
Here is an example with some of the different possible pseudo-combinations using ofThe
and the phrase "angle of the pendulum"
:
Combinator | Singular Case | Plural Case | Capital Case | Title Case |
---|---|---|---|---|
ofThe |
angle of the pendulum | angle of the pendulums | Angle of the pendulum | Angle of the Pendulum |
ofThePS |
angle of the pendulum | angles of the pendulum | Angle of the pendulum | Angle of the Pendulum |
ofTheSPPP |
angle of the pendulums | angles of the pendulums | Angle of the pendulums | Angle of the Pendulums |
ofTheTPS |
angle of the pendulum | angles of the pendulum | Angles of the pendulum | Angles of the Pendulum |
*** Note that these may not make sense in actual English, this is just an example to demonstrate notation. For more information, please visit the Haddock documentation.***
When using these combinators, try to import the lower level modules as qualified. This way, when writing code, we may be deliberate about our choices and conscious of the level of combinator that is being used. This also allows for the naming scheme to work well; each level of combinator can follow the same rules without having to be named in different ways. Sentence
level combinators should be imported as S
, NounPhrase
level as NP
, and concepts may not be qualified. This also encourages the use of more concept-level combinators, as it makes the code cleaner and easier to read.
Many of these combinators act like inserting words into the middle of an English sentence (unless noted otherwise). Please see the Haddock documentation for more details on each combinator.
Combinators with "the":
andThe
fromThe
inThe
isThe
toThe
ofThe
-
the_ofThe
(combines twoSentences
with "of the" and prepends "the" to them)
Common combinators (without "the"):
of_
ofA
or_
and_
are
in_
is
for
andIts
Uncommon combinators:
-
the_isExpctToHvC
(prepends "The" before combining with "is expected to have") -
the_ofGiv
(prepends "the" before combining with "of a given") versus
-
denotes
(inserts "denotes the") -
wrt
(inserts "with respect to") -
defnAs
(inserts "defined as")
Unusual combinators:
-
forT
(titleizes and combines twoNamedIdeas
into aSentence
using "for") -
forGen
(titleizes and takes two functions to apply toNamedIdeas
before combining into aSentence
using "for") -
forTPS
(titleizes and pluralizes firstNamedIdea
before combining into aSentence
using "for") -
forTPP
(titleizes and pluralizes bothNamedIdeas
before combining into aSentence
using "for")
These combinators have many variations, as pluralization and capitalization rules may vary greatly between different use cases. Please see the Haddock documentation for more details and the specifics of each combinator. (Subject to change: Naming convention appending NP to the end of the combinator name)
Generalized combinators (mostly used as helpers for other combinators but can still be used for a custom combinator):
-
insertString
(inserts a givenString
into twoNPs
. Plural case pluralizes second term.) -
insertSent
(inserts a givenSentence
into twoNPs
. Plural case pluralizes second term.) -
prependString
(prepends a givenString
to aNP
) -
prependSent
(prepends a givenSentence
to aNP
)
Article combinators (the, a):
the
-
theGen
(accepts a function to determine plural case) a_
-
a_Gen
(accepts a function to determine plural case)
Common combinators (appending a '
means plural case pluralizes first term. Appending ''
means plural case accepts two functions.):
ofThe
inThe
the_ofThe
for
of_
and_
Unusual combinators:
-
with
(no special plural or general case) -
of_GenGen
(accepts functions for both singular and plural cases) -
and_GenGen
(accepts functions for both singular and plural cases)
These combinators take NamedIdeas
and make a NP
from them. Because of the variety of pluralization and capitalization, there are many variants of each combinator. Please visit the Haddock documentation for more details and the specifics of each combinator. (Subject to change: Naming scheme with '
and _
)
Common combinators:
and_
andIts
andThe
for
of_
ofA
the
inThe
with
toThe
onThe
ofThe
the_ofThe
Please see Haddock documentation for more information.
NamedIdea
and NamedChunk
combinators (does not preserve abbreviations):
compoundNC
compoundNCPP
compoundNCGen
compoundNCPS
-
compoundNCGenP
(takes only one function for the first term) compoundNCPSPP
Other NP
and NamedIdea
combinators (may be moved to Drasil.Language):
combineNPNI
combineNINP
The most common (and complex) construction of a complex NounPhrase
used in Drasil is by using the Phrase
constructor. Using this constructor allows us to build up phrases with proper pluralization and capitalization. When we want to use a NounPhrase
in a Sentence
, Drasil often calls upon the Ch
constructor to hold the UID
of the NounPhrase
that will be resolved later by looking up the UID
in the ChunkDB
. The Ch
constructor also holds the style and capitalization that the term should be displayed in. The style can either be singular form, short form, or pluralized form. By doing this, each of the above combinators can be used for any of the following forms: singular without capitals, singular with first word capitalized, singular with all words capitalized, plural without capitals, plural with first word capitalized, plural with all words capitalized. So rather than having six combinators for the same phrase, we only use one and determine the specific case we need afterwards. The short forms are more rare and thus use the Gen
form of a combinator when needed.
Future changes include:
- Removing
s
,NP
naming convention and allowing qualified imports to determine the different levels of combinators. - Change method for naming different Singular and Plural operators as follows:
-
_
used for combinators that would otherwise clash with Haskell syntax - Base combinators will default plural case to
singular t1, plural t2
- append
S
andP
to specify the plural case - append
T
to specify title case - append
Gen
for general case (no specified plural case)
-
- Remove duplicate titleized versions of combinators.
- Eventually move to a richer language that can encompass semantics better, like the Grammatical Framework.
- Home
- Getting Started
- Documentation (of Drasil specifics)
- Design
-
Readings
- Drasil Papers and Documents
- Related Work and Inspiration
- Writing Documentation
- Compression as a Means to Learn Structure
- Glossary, Taxonomy, Ontology
- Grounded Theory
- Model Driven Scrapbook
- Model Transformation Languages
- ODE Definitions
- The Code Generator
- Suggested Reading
- Sustainability
- Productivity
- Reuse
- Formal Concept Analysis
- Generative Programming
- Software Documentation
- Units and Quantities
- Misc.
- WIP Projects