Spirit 2.5.2 reference card

classic Classic list List threaded Threaded
38 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Spirit 2.5.2 reference card

Richard-45
I've been wanting one of these for a while and finally found a TeX
reference card that I could suitably transform into one for Spirit.

<http://user.xmission.com/~legalize/spirit/spirit-reference.pdf>
<http://user.xmission.com/~legalize/spirit/spirit-reference.tex>

There's still some more room on there for a double-sided single-page
reference, so if you have suggestions for filling up the remaining
space, let me know.  I used the Qi reference as my source material.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Joel de Guzman
On 11/2/14, 12:47 AM, Richard wrote:
> I've been wanting one of these for a while and finally found a TeX
> reference card that I could suitably transform into one for Spirit.
>
> <http://user.xmission.com/~legalize/spirit/spirit-reference.pdf>
> <http://user.xmission.com/~legalize/spirit/spirit-reference.tex>
>
> There's still some more room on there for a double-sided single-page
> reference, so if you have suggestions for filling up the remaining
> space, let me know.  I used the Qi reference as my source material.

That is really neat, Richard. It would be nice if we can somehow
include and/or link that to the docs.

Regards,
--
Joel de Guzman
http://www.ciere.com
http://boost-spirit.com
http://www.cycfi.com/


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45

In article <m33amd$hjj$[hidden email]>,
    Joel de Guzman <[hidden email]> writes:

> On 11/2/14, 12:47 AM, Richard wrote:
> > I've been wanting one of these for a while and finally found a TeX
> > reference card that I could suitably transform into one for Spirit.
> >
> > <http://user.xmission.com/~legalize/spirit/spirit-reference.pdf>
> > <http://user.xmission.com/~legalize/spirit/spirit-reference.tex>
> >
> > There's still some more room on there for a double-sided single-page
> > reference, so if you have suggestions for filling up the remaining
> > space, let me know.  I used the Qi reference as my source material.
>
> That is really neat, Richard. It would be nice if we can somehow
> include and/or link that to the docs.

I'm happy to issue a pull request to the Spirit 2.x repository in github
for the .tex file and the Makefile sources.

The build process requires some sort of TeX installation obviously,
with tex, dvips and gs.

Do we want to commit the PDF?
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Joel de Guzman
On 11/2/14, 5:46 AM, Richard wrote:
>
> I'm happy to issue a pull request to the Spirit 2.x repository in github
> for the .tex file and the Makefile sources.
>
> The build process requires some sort of TeX installation obviously,
> with tex, dvips and gs.
>
> Do we want to commit the PDF?

PDF would be fine as well.

Regards,
--
Joel de Guzman
http://www.ciere.com
http://boost-spirit.com
http://www.cycfi.com/


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45

In article <m33qk3$r7b$[hidden email]>,
    Joel de Guzman <[hidden email]> writes:

> On 11/2/14, 5:46 AM, Richard wrote:
> >
> > I'm happy to issue a pull request to the Spirit 2.x repository in github
> > for the .tex file and the Makefile sources.
> >
> > The build process requires some sort of TeX installation obviously,
> > with tex, dvips and gs.
> >
> > Do we want to commit the PDF?
>
> PDF would be fine as well.

OK.

I was just thinking... isn't there something in Spirit that
synthesizes the attribute as std::string for char_ sequences?

I didn't find that in the reference.

I also found a few small errors in the docs, which I will log.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

sehe
On 02-11-14 02:58, Richard wrote:
> synthesizes the attribute as std::string for char_ sequences?
qI::as_string  


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45

In article <[hidden email]>,
    Seth Heeren <[hidden email]> writes:

> On 02-11-14 02:58, Richard wrote:
> > synthesizes the attribute as std::string for char_ sequences?
> qI::as_string  

Yeah, I can coerce it after the fact, but take a look at the JSON
parser here:

<http://legalizeadulthood.wordpress.com/2011/05/17/domain-specific-languages-by-martin-fowler/>

specifically:

quoted_string = lexeme['"' >> +(char_ - '"') >> '"'];

qi::rule<Iter, std::string(), ascii::space_type> quoted_string;

...nothing there is calling as_string, yet the attribute type is
clearly std::string and the rule only deals in ascii::char_.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Michael Powell-2
On Sun, Nov 2, 2014 at 10:31 AM, Richard <[hidden email]> wrote:

>
> In article <[hidden email]>,
>     Seth Heeren <[hidden email]> writes:
>
>> On 02-11-14 02:58, Richard wrote:
>> > synthesizes the attribute as std::string for char_ sequences?
>> qI::as_string
>
> Yeah, I can coerce it after the fact, but take a look at the JSON
> parser here:
>
> <http://legalizeadulthood.wordpress.com/2011/05/17/domain-specific-languages-by-martin-fowler/>
>
> specifically:
>
> quoted_string = lexeme['"' >> +(char_ - '"') >> '"'];
>
> qi::rule<Iter, std::string(), ascii::space_type> quoted_string;
>
> ...nothing there is calling as_string, yet the attribute type is
> clearly std::string and the rule only deals in ascii::char_.

Isn't std::string really just a sequence of char, anyway?

http://www.cplusplus.com/reference/string/string/

>From a Spirit perspective under the hood I couldn't say, but it seems
like a reasonable assumption that consuming a lexeme, in this case,
would synthesize a std::string from a sequence of char_.

> --
> "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
>      The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
>          The Terminals Wiki <http://terminals.classiccmp.org>
>   Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Spirit-general mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/spirit-general

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45

In article <[hidden email]>,
    Michael Powell <[hidden email]> writes:

> Isn't std::string really just a sequence of char, anyway?

Yes, but the Qi reference says that +, *, %, >>, etc. creates a vector:

<http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/quick_reference/qi_parsers/operator.html>
<http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/reference/operator/sequence.html>

In fact, even those two pages don't completely agree.  The quick
reference says the attribute of >> is tuple and the full reference shows
that it can produce a vector.

Neither page mentions that it synthesizes a std::string when A is char.

However, I think this has long since been the case and the
documentation has simply gotten out of synch.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Michael Powell-2
On Sun, Nov 2, 2014 at 12:03 PM, Richard <[hidden email]> wrote:

>
> In article <[hidden email]>,
>     Michael Powell <[hidden email]> writes:
>
>> Isn't std::string really just a sequence of char, anyway?
>
> Yes, but the Qi reference says that +, *, %, >>, etc. creates a vector:
>
> <http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/quick_reference/qi_parsers/operator.html>
> <http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/reference/operator/sequence.html>
>
> In fact, even those two pages don't completely agree.  The quick
> reference says the attribute of >> is tuple and the full reference shows
> that it can produce a vector.
>
> Neither page mentions that it synthesizes a std::string when A is char.

I'm just saying, if memory serves, verify for yourself, that at some
level, std::string is just a basic_string<char> (default?), which can
consume vector<char>, or at least be iterated like it was a vector.

Again, if memory serves; verify for yourself.

> However, I think this has long since been the case and the
> documentation has simply gotten out of synch.

Can't speak to that personally.

> --
> "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
>      The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
>          The Terminals Wiki <http://terminals.classiccmp.org>
>   Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Spirit-general mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/spirit-general

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Michael Powell-2
In reply to this post by Richard-45
On Sun, Nov 2, 2014 at 12:03 PM, Richard <[hidden email]> wrote:

>
> In article <[hidden email]>,
>     Michael Powell <[hidden email]> writes:
>
>> Isn't std::string really just a sequence of char, anyway?
>
> Yes, but the Qi reference says that +, *, %, >>, etc. creates a vector:
>
> <http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/quick_reference/qi_parsers/operator.html>
> <http://www.boost.org/doc/libs/1_56_0/libs/spirit/doc/html/spirit/qi/reference/operator/sequence.html>

I will say, having personally parsed entities using char_-iness
adapted into struct/string-iness, it works as expected.

> In fact, even those two pages don't completely agree.  The quick
> reference says the attribute of >> is tuple and the full reference shows
> that it can produce a vector.
>
> Neither page mentions that it synthesizes a std::string when A is char.
>
> However, I think this has long since been the case and the
> documentation has simply gotten out of synch.
> --
> "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
>      The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
>          The Terminals Wiki <http://terminals.classiccmp.org>
>   Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Spirit-general mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/spirit-general

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45
In reply to this post by Michael Powell-2

In article <[hidden email]>,
    Michael Powell <[hidden email]> writes:

> I'm just saying, if memory serves, verify for yourself, that at some
> level, std::string is just a basic_string<char> (default?), which can
> consume vector<char>, or at least be iterated like it was a vector.

Yes, std::string is a typedef for std::basic_string<char>.
Yes, basic_string has a push_back method and other methods that are
copatible with viewing it as a container of char's.
<http://en.cppreference.com/w/cpp/string/basic_string>

I guess what I'm saying is that the docs aren't making it clear that
the sequence operators aren't constructing a std::vector<char> and
then copying it all over again into a std::string.  It can build up
the string directly.

Digging throught the implementation, I can't determine if this is the
case or not.  I'm not an implementor of Spirit internals, so I don't
know where to look to answer this question.

For now the reference card follows the documentation, but I would like
to hear from Joel if the string attribute is synthesized directly,
or if Spirit just does an as<string> for the user at the end, copying
from vector<char> to string.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Joel de Guzman
On 11/3/14, 3:23 AM, Richard wrote:

>
> In article <[hidden email]>,
>      Michael Powell <[hidden email]> writes:
>
>> I'm just saying, if memory serves, verify for yourself, that at some
>> level, std::string is just a basic_string<char> (default?), which can
>> consume vector<char>, or at least be iterated like it was a vector.
>
> Yes, std::string is a typedef for std::basic_string<char>.
> Yes, basic_string has a push_back method and other methods that are
> copatible with viewing it as a container of char's.
> <http://en.cppreference.com/w/cpp/string/basic_string>
>
> I guess what I'm saying is that the docs aren't making it clear that
> the sequence operators aren't constructing a std::vector<char> and
> then copying it all over again into a std::string.  It can build up
> the string directly.
>
> Digging throught the implementation, I can't determine if this is the
> case or not.  I'm not an implementor of Spirit internals, so I don't
> know where to look to answer this question.
>
> For now the reference card follows the documentation, but I would like
> to hear from Joel if the string attribute is synthesized directly,
> or if Spirit just does an as<string> for the user at the end, copying
> from vector<char> to string.

There's some basic misunderstanding here. Spirit synthesizes attributes
only when it does not have information about what the user wants. For
example, when you have something like:

    p[f]

p synthesizes an attribute for f. It does not know what f wants. f
can be a template function, for example, and you can't know what
arguments to pass to it.

On the other hand, if you explicitly pass an attribute to, say,
the parse function, then Spirit will *try* to use that attribute
as long as it is compatible.

Keep in mind that "vector" in the documentation does not mean it's
limited to a std::vector. See:

   http://tinyurl.com/kpen4oc

Note:

   "Important
    In the attribute tables, we will use vector<A> and tuple<A, B...>
    as placeholders only. The notation of vector<A> stands for any STL
    container holding elements of type A and the notation tuple<A, B...>
    stands for any Boost.Fusion sequence holding A, B, ... etc. elements.
    Finally, Unused stands for unused_type."

So, it is arguably wrong to say that "docs aren't making it clear
that the sequence operators aren't constructing a std::vector<char>
and then copying it all over again into a std::string. It can build
up the string directly." It might help to re-read the docs starting
from the Attributes section. It would also help to read up on other
follow-up articles. For example:

   http://tinyurl.com/lgzgsk3
   http://tinyurl.com/ccpathx

There may be more. I'd welcome anyone who could consolidate these
information back into the base documentation.


HTH.


Regards,
--
Joel de Guzman
http://www.ciere.com
http://boost-spirit.com
http://www.cycfi.com/


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Joel de Guzman
On 11/3/14, 5:08 AM, Joel de Guzman wrote:

> On 11/3/14, 3:23 AM, Richard wrote:
>>
>> In article <[hidden email]>,
>>       Michael Powell <[hidden email]> writes:
>>
>>> I'm just saying, if memory serves, verify for yourself, that at some
>>> level, std::string is just a basic_string<char> (default?), which can
>>> consume vector<char>, or at least be iterated like it was a vector.
>>
>> Yes, std::string is a typedef for std::basic_string<char>.
>> Yes, basic_string has a push_back method and other methods that are
>> copatible with viewing it as a container of char's.
>> <http://en.cppreference.com/w/cpp/string/basic_string>
>>
>> I guess what I'm saying is that the docs aren't making it clear that
>> the sequence operators aren't constructing a std::vector<char> and
>> then copying it all over again into a std::string.  It can build up
>> the string directly.
>>
>> Digging throught the implementation, I can't determine if this is the
>> case or not.  I'm not an implementor of Spirit internals, so I don't
>> know where to look to answer this question.
>>
>> For now the reference card follows the documentation, but I would like
>> to hear from Joel if the string attribute is synthesized directly,
>> or if Spirit just does an as<string> for the user at the end, copying
>> from vector<char> to string.
>
> There's some basic misunderstanding here. Spirit synthesizes attributes
> only when it does not have information about what the user wants. For
> example, when you have something like:
>
>      p[f]
>
> p synthesizes an attribute for f. It does not know what f wants. f
> can be a template function, for example, and you can't know what
> arguments to pass to it.
>
> On the other hand, if you explicitly pass an attribute to, say,
> the parse function, then Spirit will *try* to use that attribute
> as long as it is compatible.
>
> Keep in mind that "vector" in the documentation does not mean it's
> limited to a std::vector. See:
>
>     http://tinyurl.com/kpen4oc
>
> Note:
>
>     "Important
>      In the attribute tables, we will use vector<A> and tuple<A, B...>
>      as placeholders only. The notation of vector<A> stands for any STL
>      container holding elements of type A and the notation tuple<A, B...>
>      stands for any Boost.Fusion sequence holding A, B, ... etc. elements.
>      Finally, Unused stands for unused_type."
>
> So, it is arguably wrong to say that "docs aren't making it clear
> that the sequence operators aren't constructing a std::vector<char>
> and then copying it all over again into a std::string. It can build
> up the string directly." It might help to re-read the docs starting
> from the Attributes section. It would also help to read up on other
> follow-up articles. For example:
>
>     http://tinyurl.com/lgzgsk3
>     http://tinyurl.com/ccpathx
>
> There may be more. I'd welcome anyone who could consolidate these
> information back into the base documentation.

If anyone's up to it, add these as well:

   http://boost-spirit.com/home/articles/

Regards,
--
Joel de Guzman
http://www.ciere.com
http://boost-spirit.com
http://www.cycfi.com/


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45
In reply to this post by Joel de Guzman

In article <m366gp$juj$[hidden email]>,
    Joel de Guzman <[hidden email]> writes:

> Note:
>
>    "Important
>     In the attribute tables, we will use vector<A> and tuple<A, B...>
>     as placeholders only. The notation of vector<A> stands for any STL
>     container holding elements of type A and the notation tuple<A, B...>
>     stands for any Boost.Fusion sequence holding A, B, ... etc. elements.
>     Finally, Unused stands for unused_type."

Ah, OK, that makes perfect sense now that you quote that to me :-).

Spirit is template based after all and it deals with concepts more
than it deals with specific concrete classes.

Would you accept a patch that adds a small Note: with a link to the
attributes page for any reference page that mentions vector<> as the
attribute?
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

TONGARI J
2014-11-03 9:32 GMT+08:00 Richard <[hidden email]>:

In article <m366gp$juj$[hidden email]>,
    Joel de Guzman <[hidden email]> writes:

> Note:
>
>    "Important
>     In the attribute tables, we will use vector<A> and tuple<A, B...>
>     as placeholders only. The notation of vector<A> stands for any STL
>     container holding elements of type A and the notation tuple<A, B...>
>     stands for any Boost.Fusion sequence holding A, B, ... etc. elements.
>     Finally, Unused stands for unused_type."

Ah, OK, that makes perfect sense now that you quote that to me :-).

Spirit is template based after all and it deals with concepts more
than it deals with specific concrete classes.

Would you accept a patch that adds a small Note: with a link to the
attributes page for any reference page that mentions vector<> as the
attribute?

Isn't that already the case?
"See Compound Attribute Notation." has the link.

------------------------------------------------------------------------------

_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45

In article <CANCwVhffQMYQoxzefFQuvurWzvd1Eh=BtqG9=[hidden email]>,
    TONGARI J <[hidden email]> writes:

> 2014-11-03 9:32 GMT+08:00 Richard <[hidden email]>:
> > Would you accept a patch that adds a small Note: with a link to the
> > attributes page for any reference page that mentions vector<> as the
> > attribute?
> >
>
> Isn't that already the case?
> "See Compound Attribute Notation." has the link.

Clearly this link isn't obvious enough if someone like me that is
already pretty familiar with Spirit didn't figure this out simply
because I've been away from the docs for a while.  I can only imagine
how difficult this stuff is for someone who hasn't read the docs from
end-to-end.  The rule of thumb for documentation is: if people get
confused or something isn't obvious when they read it, then it needs
improvement.

In fact, I'm just wondering if we shouldn't use vector<A> notation at
all but should instead write Sequence<A> to make it clear that this is
a concept that's being denoted and not a specific class.  I'm not sure
what the right concept is for tuple<A,B>; is it considered a model of
a container concept or a model of some other concept?
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Joel de Guzman
On 11/3/14, 10:41 AM, Richard wrote:

>
> In article <CANCwVhffQMYQoxzefFQuvurWzvd1Eh=BtqG9=[hidden email]>,
>      TONGARI J <[hidden email]> writes:
>
>> 2014-11-03 9:32 GMT+08:00 Richard <[hidden email]>:
>>> Would you accept a patch that adds a small Note: with a link to the
>>> attributes page for any reference page that mentions vector<> as the
>>> attribute?
>>>
>>
>> Isn't that already the case?
>> "See Compound Attribute Notation." has the link.
>
> Clearly this link isn't obvious enough if someone like me that is
> already pretty familiar with Spirit didn't figure this out simply
> because I've been away from the docs for a while.  I can only imagine
> how difficult this stuff is for someone who hasn't read the docs from
> end-to-end.  The rule of thumb for documentation is: if people get
> confused or something isn't obvious when they read it, then it needs
> improvement.
>
> In fact, I'm just wondering if we shouldn't use vector<A> notation at
> all but should instead write Sequence<A> to make it clear that this is
> a concept that's being denoted and not a specific class.  I'm not sure
> what the right concept is for tuple<A,B>; is it considered a model of
> a container concept or a model of some other concept?

Actually, what I would really like is a consolidation of all the docs
I linked to thus far into the current docs. That may include some
clarification such as what you are probably suggesting. It wouldn't need
to be a total rewrite. Perhaps some restructuring would suffice. Attribute
handling is the most misunderstood part of Spirit. Perhaps it would make
sense to write a complete chapter with the articles I linked to along
with the current docs as basis.

I'm not sure about changing the concept names. tuple<A,B> is explained
in the docs -- it is a fusion *sequence*. That makes it all the more
difficult to allow a Sequence<A> concept. Unless there's a better
suggestion, I'd say we keep it as is.

Regards,
--
Joel de Guzman
http://www.ciere.com
http://boost-spirit.com
http://www.cycfi.com/


------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

sehe
In reply to this post by Richard-45
On 02-11-14 17:31, Richard wrote:
> ...nothing there is calling as_string, yet the attribute type is
> clearly std::string and the rule only deals in ascii::char_.
There is a difference between synthesized and exposed/declared attributes.

There are builtin transformation, attribute assignment rules (and even
customization hooks for your own). One of these allows inserting
characters into any sequence here.

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
Reply | Threaded
Open this post in threaded view
|

Re: Spirit 2.5.2 reference card

Richard-45
In reply to this post by Joel de Guzman

In article <m3708g$7mn$[hidden email]>,
    Joel de Guzman <[hidden email]> writes:

> Actually, what I would really like is a consolidation of all the docs
> I linked to thus far into the current docs. That may include some
> clarification such as what you are probably suggesting. It wouldn't need
> to be a total rewrite.

Agreed.

> Attribute handling is the most misunderstood part of Spirit.

Agreed.  I think it is also one of the most powerful aspects of
Spirit as it is the missing link between "how do I match this input?"
and "how do I get it into *my* data structure?".

> I'm not sure about changing the concept names. tuple<A,B> is explained
> in the docs -- it is a fusion *sequence*. That makes it all the more
> difficult to allow a Sequence<A> concept. Unless there's a better
> suggestion, I'd say we keep it as is.

How about replacing vector<A> with Sequence<A> (the Sequence concept
from the standard library) and tuple<A,B> with Fusion.Sequence<A,B>?

Is it specifically required to be a particular one of the concepts
Forward Sequence, Bidirectional Sequence, Random Access Sequence, or
Associative Sequence?

Speaking of Fusion, since we have some more room on the reference
card, should we add some material about Fusion?

I added some material about Phoenix placeholders provided by Spirit,
but perhaps a little more about Phoenix should be provided?
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>

------------------------------------------------------------------------------
_______________________________________________
Spirit-general mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/spirit-general
12