Cypress2Spec.txt

Specification for a class-per-file version of Cypress.


Motivation (***Needs fleshing out)
* Interchange between Smalltalk implementations
* Management of Smalltalk code in Git or Subversion
* Ability to edit Smalltalk code in plain-text editors, as well as within a Smalltalk IDE
* Meaningful use of third-party diffing tools for Smalltalk code

Declarative 
Traditional Smalltalk fileins are imperative -- they execute code as the file is parsed.
Cypress is declarative. In a typical implementation, Cypress files are parsed into a graph of definition objects (class definition, method definition, etc.) and these definition objects are then analyzed and either applied to the system or delivered to tools that can manipulate the definitions directly.


=============

Example class file (rough example, hopefully close enough to give the flavor):

***Needs updating for containment in {} and () instead of -:

-: File
   { 'Standard' : 'Cypress2',
     'FileFormat' : 'FilePerClass',
     'CopyrightNotice' : 'Copyright 2016 Martin McClure' }
-: Class
   { 'Name' : 'ExampleClass',
     'Superclass' : 'Object',
     'gsSymbolDictionary' : 'UserGlobals',
     'Instance Variables' : [ 'instVar1', 'instVar2'] }
-: InstanceMethods
-: Method
   { 'protocol' : 'accessing',
     'timestamp' : '2016-12-14T23:48:38Z',
     'author' : 'Martin McClure' }
instVar1
  ^ instVar1
-: Method
   { 'protocol' : 'accessing',
     'timestamp' : '2016-12-14T23:49:17Z',
     'author' : 'Martin McClure' }
instVar1: anObject
  instVar1 := anObject     
   
=============

SYNTAX:

Encoding Shall be UTF-8

This syntax is described in PEG syntax, see peg-popl04.pdf

*** Need to think about extension methods.

----------

ClassFile <- Spacing FileSectionHeader ClassDefinition EndOfFile

FileSectionHeader <- SECTIONMARK 'File' Spacing SectionProperties

ClassDefinition <- ClassSectionHeader ClassMethodsSection? InstanceMethodSection?

ClassSectionHeader <- SECTIONMARK 'Class' Spacing SectionProperties

ClassMethodsSection <- ClassMethodsSectionHeader MethodSections

ClassMethodsSectionHeader <- SECTIONMARK 'ClassMethods' Spacing SectionProperties

InstanceMethodsSection <- InstanceMethodsSectionHeader MethodSections

InstanceMethodsSectionHeader <- SECTIONMARK 'InstanceMethods' Spacing SectionProperties

MethodSections <- MethodSection*

MethodSection <- MethodSectionHeader SmalltalkMethodBody

MethodSectionHeader <- SECTIONMARK 'Method' Spacing SectionProperties

SmalltalkMethodBody <- (MethodCode / SmalltalkStringLiteral / SmalltalkComment)* 
   #Should be valid to a Smalltalk compiler

MethodCode <- (!(EndOfFile / SECTIONMARK / "'" / '"') . )*

SmalltalkComment <- '"' ( !'"' . )* '"'

SmalltalkStringLiteral <- "'" ("''" / (!"'" . ))* "'"

SectionProperties <- LimitedStonMap / Spacing

Spacing <- WhitespaceCharacter*

WhitespaceCharacter <- ' ' / '\t' / '\r' / '\n'

EndOfFile <- !.

SECTIONMARK <- '-:' Spacing

---

STON subset for section properties:

LimitedStonMap <- '{' Spacing LimitedStonMember* '}' Spacing

LimitedStonMember <- LimitedStonPair (comma LimitedStonPair)*

LimitedStonPair <- StonString colon LimitedStonValue

StonString <- "'" StonStringChar* "'" Spacing

StonStringChar <- !['"\\] PrintableAsciiCharacter / StonEscapedChar

PrintableAsciiCharacter <- [ -~]

StonEscapedChar <- '\\' ['"\\/bfnrt] / StonUnicodeChar

StonUnicodeChar <- '\u' hexdigit hexdigit hexdigit hexdigit

hexdigit <- [0-9] / [a-f] / [A-F]

LimitedStonValue <- StonPrimitiveValue / LimitedStonObject 

StonPrimitiveValue <- 'nil' Spacing 
                   / 'true' Spacing 
                   / 'false' Spacing 
                   / StonNumber 
                   / StonString

LimitedStonObject <- LimitedStonMap / LimitedStonList

LimitedStonList <- '[' LimitedStonValues ']'

LimitedStonValues <- LimitedStonValue (comma LimitedStonValue)*

StonNumber <- StonInt / StonFloat

StonInt <- '-'? ('0' / [1-9] [0-9]*)

StonFloat <- StonInt (StonFractionalPart / StonExponent / StonFractionalPart StonExponent)

StonFractionalPart <- '.' [0-9]+ 

StonExponent <- [Ee] [-+]? [0-9]+

comma <- ',' Spacing
colon <- ':' Spacing

=========

=========

Each level of section has an optional properties definition in a limited subset of STON.

=========

File-per-method Cypress

Directory structure 
Directories have uppercase names, files lower-case

RepositoryDirectory (any name)
properties.ston

=========

File-per-package Cypress
TBD, an extension of file-per-class