[Swift-devel] Swift reference manual and syntax specification

[Michael Wilde]

Hi All,

We have an activity underway within the ExTENCI project to improve Swift's tutorial and documentation, in collaboration with Amy Apon (chair of Computer Science at Clemson and OSG collaborator) and Clemson graduate student Eric Skogen.

I suggested that we use support questions on the swift-* email lists as one guide to where documentation needs improvement, citing a recent question from a new user who didn't understand what can go in an app() function.

Amy recently suggested that we publish a syntax specification for Swift (which is a great idea and long overdue) and pointed out that the syntax spec could/would have made clear to this new user that you can't put an assignment in an app def.

What I believe we need for Swift is a top-notch User Guide that can double as a hands-on tutorial, and a separate, concise but complete Reference Manual that precisely states language syntax and semantics, and can be used by both users (to answer questions not made clear in the User Guide) and developers (to discuss subtleties or proposed changes in semantics and to deal with implementation issues).

While the User Guide needs to be organized in a reasonable order for exposing the language, the Reference Manual needs to be laid out more top-down (in terms of compilation units) and bottom-up (in terms of lexical issues).

Eric, David, and Ketan are discussing and working on the User Guide. Ive asked Ketan to see if the informal BNF-like syntax of the classic K&R C book can be readily adapted to Swift, and also suggested that the concise compact style of the Swift/T User Guide is in fact more of a reference manual already, and could form the basis of a complete reference manual that ideally can serve both Swift/K and Swift/T.

We'll need and be having a lot more discussion on both the User Guide and Reference Manual, but with this e-mail I wanted to move all such discussion to this list (swift-devel).

- Mike

----- Original Message -----
> From: "Amy Apon" <aapon at clemson.edu>
> To: "Michael Wilde" <wilde at mcs.anl.gov>
> Cc: "Eric Skogen" <eskogen at g.clemson.edu>, "David Kelly" <davidk at ci.uchicago.edu>, "Ketan Maheshwari"
> <ketan at mcs.anl.gov>
> Sent: Sunday, March 10, 2013 1:05:54 PM
> Subject: Re: [Swift-user] Variable Declaration
> 
> Mike,
> 
> 
> This is a good idea -- looking at support questions to understand
> where the "pain points" are.
> 
> 
> This particular question is related to our conversation on the last
> call. If we could come up with a grammar or grammar-like description
> of Swift, then explaining the concept below (that an app()
> function's body is restricted to contain a single command line
> template and nothing else),would be explained with a tutorial about
> the grammar. Are we still looking at this?
> 
> 
> I would like to schedule another call that includes you, me, and
> Eric, I think, to keep in touch. How does your time look on
> Wednesday afternoon this week?
> 
> 
> Amy
> 
> 
> 
> 
> 
> Amy Apon, Ph.D.
> Professor and Chair, Division of Computer Science, School of
> Computing
> Clemson University
> 221 McAdams
> Phone: 864-656-5769
> 
> 
> 
> 
> 
> 
> 
> 
> On Sun, Mar 10, 2013 at 12:30 PM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> Eric, All,
> 
> I think we can gain a lot of insight into documentation/training
> needs by observing the questions users come with when first using
> Swift, such as this one.
> 
> - restrictions on what can be in an app() body, and how you code
> around them
> 
> - guidance on the use of types and type names
> 
> In other words, we can look at support questions and ask "how can the
> learning roadmap make such support questions less likely to happen".
> 
> Mike
> 
> ----- Forwarded Message -----
> From: "Tim Armstrong" < tim.g.armstrong at gmail.com >
> To: "Michael Wilde" < wilde at mcs.anl.gov >
> Sent: Saturday, March 9, 2013 5:56:39 PM
> Subject: Re: [Swift-user] Variable Declaration
> 
> What Mike said. I was also going to say that your line:
> 
> type string;
> 
> may cause problems: string is a built-in type and you don't need to
> define it.
> 
> - Tim
> 
> 
> On Sat, Mar 9, 2013 at 5:55 PM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> Jay,
> 
> An app() function's body is restricted to contain a single command
> line template and nothing else. So instead of:
> 
> 
> app (messagefile t) parse(messagefile n) {
> string v = @regexp("abcdefghi", "c(def)g","monkey");
> echo @extractint(n) stdout=@filename(t);
> }
> 
> ...you need create a separate ("compound") function to do things like
> string v=(). You can embed arbitrary expressions in the app() body,
> but it can only have one semicolon-terminated command. Thats the
> likely cause of the syntax error.
> 
> Also note that your statement "string v = ..." is creating a value
> that as far as I can see is not used anywhere, so you may want to
> re-examine that logic.
> 
> - Mike
> 
> 
> 
> ----- Original Message -----
> > From: "Jay Lee" < jlee734 at gmail.com >
> > To: swift-user at ci.uchicago.edu
> > Sent: Saturday, March 9, 2013 5:48:17 PM
> > Subject: [Swift-user] Variable Declaration
> > 
> > 
> > Hello,
> > 
> > I just started with swift today, so excuse my lack of knowledge. I
> > have the following code:
> > 
> > type messagefile;
> > type string;
> > 
> > app (messagefile t) parse(messagefile n) {
> > string v = @regexp("abcdefghi", "c(def)g","monkey");
> > echo @extractint(n) stdout=@filename(t);
> > }
> > 
> > app (messagefile t) greeting() {
> > echo "Hello, world!" stdout=@filename(t);
> > }
> > 
> > messagefile outfile <"hello.txt">;
> > messagefile input <"compile.txt">;
> > 
> > outfile = parse(input);
> > 
> > 
> > 
> > I get an error: Could not compile SwiftScript source: line 6:10:
> > expecting a semicolon, found '='
> > 
> > I found that there are mappers that can be used to declare
> > variables
> > (namely files), but are these required?
> > 
> > 
> > 
> > _______________________________________________
> > Swift-user mailing list
> > Swift-user at ci.uchicago.edu
> > https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-user
> _______________________________________________
> Swift-user mailing list
> Swift-user at ci.uchicago.edu
> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-user
> 
> 
>