Update TableGen LangIntro.rst

[chenwj]

Summary

Update a few places in TableGen LangIntro.rst.

• Only one-line double-quoted string literal considered as string type, see how check is done in TGLexer::LexString() (TGLexer.cpp).

• string type value can be converted to code type, but not the other way around. See StringRecTy::classof and CodeRecTy::classof (Record.h).

• Clarify value{15-17} and value{17-15} actually are different things, as discussed on About TableGen RangeList.

[chenwj]

fix typo.

[chenwj]

Ping? Any comment? :-)

[chenwj]

Ping? :-)

[kparzysz]

docs/TableGen/LangIntro.rst

134

How about "access to an ordered sequence of bits of a value, in particular value{15-17} produces an order that is the reverse of value{17-15}."

[asb]

Hi, thanks for the patch. My feedback is:

1. Limitations of literal formats shouldn't be discussed when introducing the types.
2. Perhaps outside the scope of this patch, but it does seem a little odd that a simple string literal can be assigned to either a string or code variable, but code fragment literals can't be assigned to string variables (at least on the couple of months old build on LLVM I have on this machine). The existing description that a code fragment is "just a multiline string literal" seems incorrect due to this.

docs/TableGen/LangIntro.rst

59

It's correct that string literals can't span multiple lines, but I think this really belongs in the discussion later in the document about TableGen values and expressions which documents literal formats.

[kparzysz]

Also, does the document mention expressions like "Inst{31,27-25,14}", where the bit accesses are in a comma-separated list?

[chenwj]

Address review comments.

[chenwj]

In D32117#736630, @kparzysz wrote:

Also, does the document mention expressions like "Inst{31,27-25,14}", where the bit accesses are in a comma-separated list?

As far I can tell, no. I don't see such example mentioned in this document. Would you like to add one?

[chenwj]

In D32117#736622, @asb wrote:

Hi, thanks for the patch. My feedback is:

1. Limitations of literal formats shouldn't be discussed when introducing the types.
2. Perhaps outside the scope of this patch, but it does seem a little odd that a simple string literal can be assigned to either a string or code variable, but code fragment literals can't be assigned to string variables (at least on the couple of months old build on LLVM I have on this machine). The existing description that a code fragment is "just a multiline string literal" seems incorrect due to this.

I think I already addressed the item one? As for item two, how do you want to rephrase it?

[kparzysz]

In D32117#739399, @chenwj wrote:

As far I can tell, no. I don't see such example mentioned in this document. Would you like to add one?

Probably not in this review. Otherwise you could keep updating it forever. From my point of view, LGTM.

[chenwj]

@asb And you? :-)

[asb]

Thank you @chenwj, this is definitely an improvement over the current documentation. Would you like me to commit?

[chenwj]

In D32117#740495, @asb wrote:

Thank you @chenwj, this is definitely an improvement over the current documentation. Would you like me to commit?

@asb Go ahead! Thanks. :-)

[chenwj]

@asb Ping? :-)

[asb]

Patch committed, many thanks for your contribution @chenwj.

[chenwj]

In D32117#743341, @asb wrote:

Patch committed, many thanks for your contribution @chenwj.

Thanks. ;)

docs/TableGen/LangIntro.rst

 ``bit``
     A 'bit' is a boolean value that can hold either 0 or 1.
 
 ``int``
     The 'int' type represents a simple 32-bit integer value, such as 5.
 
 ``string``
     The 'string' type represents an ordered sequence of characters of arbitrary
     length.
 
+``code``
+    The `code` type represents a code fragment, which can be single/multi-line
+    string literal.
+
 ``bits<n>``
     A 'bits' type is an arbitrary, but fixed, size integer that is broken up
     into individual bits.  This type is useful because it can handle some bits
     being defined while others are undefined.
 
 ``list<ty>``
     This type represents a list whose elements are some other type.  The
     contained type is arbitrary: it can even be another list type.

 
 ``7``
     decimal integer value
 
 ``0x7F``
     hexadecimal integer value
 
 ``"foo"``
-    string value
+    a single-line string value, can be assigned to ``string`` or ``code`` variable.
 
 ``[{ ... }]``
     usually called a "code fragment", but is just a multiline string literal
 
 ``[ X, Y, Z ]<type>``
     list value.  <type> is the type of the list element and is usually optional.
     In rare cases, TableGen is unable to deduce the element type in which case
     the user must specify it explicitly.
 
 ``{ a, b, 0b10 }``
     initializer for a "bits<4>" value.
     1-bit from "a", 1-bit from "b", 2-bits from 0b10.
 
 ``value``
     value reference
 
 ``value{17}``
     access to one bit of a value
 
 ``value{15-17}``
-    access to multiple bits of a value
+    access to an ordered sequence of bits of a value, in particular ``value{15-17}``
+    produces an order that is the reverse of ``value{17-15}``.
 
 ``DEF``
     reference to a record definition
 
 ``CLASS<val list>``
     reference to a new anonymous definition of CLASS with the specified template
     arguments.