From 49f9edfc00beb8148de2f79321144942e7cf8a69 Mon Sep 17 00:00:00 2001 From: Shibatan Date: Mon, 3 Dec 2018 18:47:29 -0800 Subject: [PATCH 1/2] Proofread readme file Committer: Shibatan On branch add-shibatan Changes to be committed: modified: README.md Untracked files: .DS_Store --- README.md | 74 +++++++++++++++++++++++++++---------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 03da20f..ecc8334 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 + 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. @@ -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 there and link 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. 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, primarily for building a test suite to verify that + 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. - 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 - 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. ### 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 +will be manually added as language definitions, growing the schema +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 roundtrip 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. +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 +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 @@ -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 From 8523299f318e3952b59a848a3516d90b021b2474 Mon Sep 17 00:00:00 2001 From: shibatan Date: Mon, 3 Dec 2018 21:23:03 -0800 Subject: [PATCH 2/2] Proofreading fixes to previous readme commit --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ecc8334..f2dc0ae 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ 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 there 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 @@ -40,9 +40,9 @@ accessible and useful to students of language theory. 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 that - the language definitions are able to parse files at useful levels of - detail. Again, focusing on style-defined subsets of languages, which are + 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 @@ -62,7 +62,7 @@ These phases will be slightly overlapping. The language definitions found at https://github.com/coala/coala/tree/master/coalib/bearlib/languages -will be manually added as language definitions, growing the schema +will be manually added as language definitions here, growing the schema 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. @@ -75,7 +75,7 @@ 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 roundtrip the language definitions. This will provide +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. @@ -88,7 +88,7 @@ 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. The priority, however, will be accurately describing well-established -style guides, and important features of commonly used linters of various +style guides and important features of commonly used linters of various languages. ### Phase 4: Replace coala aspects