Add PowerShell language specification document

"Windows PowerShell Language Specification version 3.0" was a great resource. Ever since then, we have been asking for Microsoft to release the specifications for later versions. Now that it's open source, there is no reason not to release the specification for 6.0. Please add the document here or otherwise release it.

The language specification has not been updated for more recent versions.

One of the original hopes in writing the document was that we'd see other implementations of PowerShell, especially on Linux. Pash made use of the document some, but I believe they found it rather incomplete.

Now that the official implementation is open source, I'm guessing the biggest value of the language specification is as an aid to learning the language. Do people agree with this?

I also wonder if the community would be willing to help update it.

I believe that we must create the document.
This is useful not only for language learning.
Now the language has become quite complicated and lack of formal definitions will hinder its further development.
It would be a good practice to first approve new formal specification of language extensions in the document before implementation.

Previously we need to specify what a notation we will use? We need a document with its description.
Also, we need to define the format of the document. Will this .md file, wiki or something else? Maybe PG will do the document workpiece in the correct place to start the process?

Inspiration:

C# Language Specification
TypeScript started with a formal spec but does not maintain it any more. The truth is now in PR documentation and this website, which includes a Handbook.

I think there's nothing wrong with keeping it maintained as markdown files in this or another repository. Something like Jekyll can be used to automatically keep static site pages up to date with the current versions of the MD documents in the repo. It seems the most accessible and easily updatable method to use, at least at first glance. 😄

Also, consider pandoc to transform to many more formats.

Bruce Payette (@BrucePay)

I think a formalized specification (including a grammar) would allow us as a community to support more than just .NET for tools to integrate PowerShell. The first thing I found while searching for a PowerShell grammar is an incomplete document from 2006.

https://devblogs.microsoft.com/powershell/powershell-grammar/

Is there any advocacy for this issue today? cc/ Bruce Payette (@BrucePay)

PowerShell
PowerShell Grammar | PowerShell
A number of people have asked about the PowerShell grammar. Here is a draft write up (I’ve also included it as an attachement) that George Xie and Bruce Payette are working on. Grammar of PowerShell (formerly known as Monad) is separated into parsing rules and tokenizing rules.

@Halkcyon, you can download the PowerShell 3.0 specification doc from 2012, that I referenced in my original post above.
https://www.microsoft.com/en-us/download/confirmation.aspx?id=36389

When I opened this issue 5 years ago, I mistakenly assumed such a document was created as part of architecting and creating each version of PowerShell. I found the original to be an interesting reference, and a very helpful part of my continuing PowerShell education, and I was hoping public release of a current version would be simple.

Unfortunately, it is not so simple. But the issue is still open, and after 5 years, I expect it should be getting to the top of the list any day now. Any day now.

Download Windows PowerShell Language Specification Version 3.0 from Official Microsoft Download Center
Language specification for Windows PowerShell 3.0.

Tim Curwick (@TimCurwick)

Tim Curwick (@TimCurwick) If it's in the community's interest that PowerShell is not "just a Windows thing", then it is in their interest to produce a grammar that other tools can produce and use. Thanks for that reference, but we have quite a few new things in the past nine years 😅

Tim Curwick (@TimCurwick)

Tim Curwick (@TimCurwick) If it's in the community's interest that PowerShell is not "just a Windows thing",

Can you clarify this point? PowerShell is already cross platform.

then it is in their interest to produce a grammar that other tools can produce and use. Thanks for that reference, but we have quite a few new things in the past nine years 😅

Are you asking for something similar to ECMA-335 for CLI? PowerShell isn't a set of behavioral rules that one can implement. I guess it technically could be, but such a document would be exponentially larger than EMCA-335.

PowerShell Grammer:
v5.1
v7.0
v7.1
The document includes:
B.1 Lexical grammar
B.2 Syntactic grammar

PowerShell Grammer: v5.1 v7.0 v7.1 The document includes: B.1 Lexical grammar B.2 Syntactic grammar

These three documents are actually identical among different PowerShell versions.

I noted that the Parser.cs includes blocks like this:

PowerShell/src/System.Management.Automation/engine/parser/Parser.cs

Lines 6789 to 6826 in ad2bf78

    
           // G  binary-expression: 
        
           // G      bitwise-expression 
        
           // G      binary-expression   '-and'   new-lines:opt   bitwise-expression 
        
           // G      binary-expression   '-or'   new-lines:opt   bitwise-expression 
        
           // G      binary-expression   '-xor'   new-lines:opt   bitwise-expression 
        
           // G 
        
           // G  bitwise-expression: 
        
           // G      comparison-expression 
        
           // G      bitwise-expression   '-band'   new-lines:opt   comparison-expression 
        
           // G      bitwise-expression   '-bor'   new-lines:opt   comparison-expression 
        
           // G      bitwise-expression   '-bxor'   new-lines:opt   comparison-expression 
        
           // G 
        
           // G  comparison-expression: 
        
           // G      nullcoalesce-expression 
        
           // G      comparison-expression   comparison-operator   new-lines:opt   nullcoalesce-expression 
        
           // G 
        
           // G  nullcoalesce-expression: 
        
           // G      additive-expression 
        
           // G      nullcoalesce-expression   '??'   new-lines:opt   additive-expression 
        
           // G 
        
           // G  additive-expression: 
        
           // G      multiplicative-expression 
        
           // G      additive-expression   '+'   new-lines:opt   multiplicative-expression 
        
           // G      additive-expression   dash   new-lines:opt   multiplicative-expression 
        
           // G 
        
           // G  multiplicative-expression: 
        
           // G      format-expression 
        
           // G      multiplicative-expression   '*'   new-lines:opt   format-expression 
        
           // G      multiplicative-expression   '/'   new-lines:opt   format-expression 
        
           // G      multiplicative-expression   '%'   new-lines:opt   format-expression 
        
           // G 
        
           // G  format-expression: 
        
           // G      range-expression 
        
           // G      format-expression   format-operator    new-lines:opt   range-expression 
        
           // G 
        
           // G  range-expression: 
        
           // G      array-literal-expression 
        
           // G      range-expression   '..'   new-lines:opt   array-literal-expression

They look like they were written from some kind of formal specification. Is it available somewhere else? Or is it expected that the whole specification is possible to reconstruct from these // G comments?

Navigation Menu

Repository navigation

Add PowerShell language specification document #2254

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	// G binary-expression:
	// G bitwise-expression
	// G binary-expression '-and' new-lines:opt bitwise-expression
	// G binary-expression '-or' new-lines:opt bitwise-expression
	// G binary-expression '-xor' new-lines:opt bitwise-expression
	// G
	// G bitwise-expression:
	// G comparison-expression
	// G bitwise-expression '-band' new-lines:opt comparison-expression
	// G bitwise-expression '-bor' new-lines:opt comparison-expression
	// G bitwise-expression '-bxor' new-lines:opt comparison-expression
	// G
	// G comparison-expression:
	// G nullcoalesce-expression
	// G comparison-expression comparison-operator new-lines:opt nullcoalesce-expression
	// G
	// G nullcoalesce-expression:
	// G additive-expression
	// G nullcoalesce-expression '??' new-lines:opt additive-expression
	// G
	// G additive-expression:
	// G multiplicative-expression
	// G additive-expression '+' new-lines:opt multiplicative-expression
	// G additive-expression dash new-lines:opt multiplicative-expression
	// G
	// G multiplicative-expression:
	// G format-expression
	// G multiplicative-expression '*' new-lines:opt format-expression
	// G multiplicative-expression '/' new-lines:opt format-expression
	// G multiplicative-expression '%' new-lines:opt format-expression
	// G
	// G format-expression:
	// G range-expression
	// G format-expression format-operator new-lines:opt range-expression
	// G
	// G range-expression:
	// G array-literal-expression
	// G range-expression '..' new-lines:opt array-literal-expression

Add PowerShell language specification document #2254

Description

Activity

lzybkr commented on Sep 15, 2016

iSazonov commented on Jan 10, 2017

jawn commented on Oct 18, 2018

vexx32 commented on Oct 18, 2018

jawn commented on Oct 18, 2018

morsley commented on Feb 1, 2021

TimCurwick commented on Feb 1, 2021

morsley commented on Feb 1, 2021

SeeminglyScience commented on Feb 4, 2021

moh-hassan commented on Oct 2, 2021

Brainor commented on Sep 20, 2023

ForNeVeR commented on Mar 10, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions