Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Proofreading of readme file + fix for issue #76 #86

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Proofreading of readme file + fix for issue #76 #86

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
49f9edf
Proofread readme file
Dec 4, 2018
8523299
Proofreading fixes to previous readme commit
Dec 4, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 37 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# coAST

coAST is a universal abstract syntax tree that allows to easily analyze
each programming language. Especially adding new languages should be easy and
each programming language. Adding new languages should be easy and
generic.

## Goals
Expand All @@ -11,8 +11,8 @@ generic.
language can be obtained by reading online resources rather than code.

2. Provide multiple usable levels of parse-ability, so that a file can
be accurately split into parts which are not yet parse-able, or the
use case has no benefit in parsing, and the parts may be modified
be accurately split into parts which are not yet parse-able -- or the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why? It seems grammatically correct earlier.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The number of commas made the sentence confusing to read. This portion of the sentence was an aside, so I enclosed it in en dashes.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The number of commas made the sentence confusing to read. This portion of the sentence was an aside, so I enclosed it in en dashes.

Copy link
Member

@siddhpant siddhpant Dec 4, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add and then the parts may be modified while retaining the commas?

use case has no benefit in parsing -- and the parts may be modified
and re-joined into an otherwise semantically equivalent file.

Performance and algorithmic beauty are not goals.
Expand All @@ -21,83 +21,83 @@ Sensitive Tree.

To achieve the first goal, the primary output of this repository is a
static website which allows the reader to understand the definitions
contained here, and link to other online resources where more information
contained here and links to other online resources where more information
can be obtained.

Links to Wikidata, Antlr definitions, E(BNF) files, example files, will
be integral components of the definitions here.
be integral components of the definitions there.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see previous comment on here vs there


Terminology used to describe language components will be consistent
across languages where-ever possible, and defer to terminology used
in academic literature or study guides, to make these definitions more
across languages wherever possible, and defer to terminology used
in academic literature or study guides to make these definitions more
accessible and useful to students of language theory.

## Stages

1. Organically grow a human readable fact based database of any syntax,
stored in YAML files, covering any language from large and complicated
programming languages down to strings like a URL, especially focusing
on style description which describe a subset of a language.
1. Organically grow a human-readable fact-based database of any syntax --
stored in YAML files -- covering any language, from large and complicated
programming languages down to strings like URLs, especially focusing
on style descriptions which describe a subset of a language.

2. Create programs to load these definitions and convert input files
into a universal AST, primarily for building a test suite to verify the
language definitions are able to parse files at useful levels of detail,
again focusing on style-defined subsets of languages which are easier
and also more useful.
into a universal AST. This is primarily for building a test suite to verify
that the language definitions are able to parse files at useful levels of
detail, focusing on style-defined subsets of languages, which are
easier and also more useful.

These programs may use existing parsers, by converting the coAST
These programs may use existing parsers by converting the coAST
definitions into metasyntax used by other parsing toolkits, such as BNF
and derivatives, Antlr .g4, and augeas.

3. Standardise the definition schema once a sufficiently large number
of language definitions have been adequately verified to determine
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adequately provides a sort of commitment.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted, will change.

the schema is able to usefully describe most concepts found in
commonly used grammars.
of language definitions have been verified to determine that
the schema can usefully describe most concepts found in
commonly-used grammars.

## Phases

These phases will be overlapping slightly.
These phases will be slightly overlapping.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to change the position of overlapping, IMO.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do believe it's correct both ways, but it reads more naturally to have the adverb before that thing that it modifies, imo.


### Phase 1: Replace coala language definitions

The language definitions found at
https://github.com/coala/coala/tree/master/coalib/bearlib/languages
will be manually added as language definitions here, growing the schema
as necessary. Once the import of facts is complete, a generator will
as necessary. Once the import of facts is complete, a generator will
create the coala language definitions from a snapshot of the coAST language
definitions, putting the collated coAST definitions into use.

### Phase 2: Import other language definitions

There are many other collections of language definitions.
Initially the coAST definitions will only link to these external resources,
and then in the second phase those external grammars will be converted
into coAST facts, using batch import tools or manually where necessary.
Initially, the coAST definitions will only link to these external resources.
In the second phase, those external grammars will be converted
into coAST facts using batch import tools, or manually where necessary.

In this phase tools to convert the coAST definitions into other syntax
will be needed, to round trip the language definitions, providing verification
that the imports are complete, or that partial definitions allow correct
partial parsing of those languages where complete parsing is too complex.
In this phase, tools to convert the coAST definitions into other syntax
will be needed to round-trip the language definitions. This will provide
verification that the imports are complete, or that partial definitions
allow correct partial parsing of those languages where complete parsing is
too complex.

### Phase 3: Create language style definitions

Create declarative descriptions of common styles, such as the Google Python
coding guidelines, and Airbnb JavaScript style.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't remove oxford comma.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not an Oxford comma.
“Such as X and Y”.
Not “such as X, and Y.”

Copy link
Member

@siddhpant siddhpant Dec 4, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh right.
Resolve this conversation if possible :-)

coding guidelines and Airbnb JavaScript style.

The schema for describing styles will borrow from the coala aspects
definitions, and should allow users to define their own custom styles,
however the priority will be accurately describing well established
style guides, and important features of commonly used linters of various
definitions, and should allow users to define their own custom styles.
The priority, however, will be accurately describing well-established
style guides and important features of commonly used linters of various
languages.

### Phase 4: Replace coala aspects

coala aspects development is driven by the needs of users, the complexity
of bears, and pre-existing implementation choices of coala.
of bears, and the pre-existing implementation choices of coala.

For avoid these influences causing incorrect design decisions in coAST,
importing of aspects will not be considered until after style definitions
are in place.
To avoid causing incorrect design decisions in coAST, importing of aspects
will not be considered until after style definitions are in place.

# Authors

Expand All @@ -114,5 +114,5 @@ The website templates and assets included in this repository are released
under the Creative Commons Share-alike license 4.0.
https://creativecommons.org/licenses/by-sa/4.0/

Any code in this repository is to be release under the MIT license.
Any code in this repository is to be released under the MIT license.
https://opensource.org/licenses/MIT