Did some extensive editing of the grammar tutorial. #1187
Conversation
|
Unfortunately, I cannot properly review it(hence the delay), though the conflicts were cause by my last merge. They need to be resolved before we move forward. I'll cast someone great enough to review it tomorrow. |
|
@Altai-man , sounds good. |
|
@Altai-man Do you want someone to review it for grammar/spelling stuff? Or are you looking for factual correctness? |
|
I think I got the grammar down, and mostly want to make sure the facts are
right/I didn't make a mistake. But it's all fair game.
Thanks.
…On Tue, Feb 14, 2017 at 7:27 PM, Cale ***@***.***> wrote:
@Altai-man <https://github.com/Altai-man> Do you want someone to review
it for grammar/spelling stuff? Or are you looking for factual correctness?
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#1187 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/ACzBpyFQqhEWq5ATm-df_WshvHFoW2qaks5rcnC4gaJpZM4L7w8g>
.
|
|
@WildYorkies, if the meaning is the same, then we need to check, does that rewording really made things better/more native or it is just rewording. If some pieces was changed greatly, we need to check it too, But examples wasn't changed, so it makes me think that it is only grammar/style that needs to be reviewed. |
|
@Altai-man Let me go through the tutorial today on @antquinonez 's branch. I've never done it. Can at least give my thoughts on clarity. |
|
@WildYorkies, I'm not a boss here, so you can do as you think appropriate without my permission. I'm personally 👍 for any review of this. |
| example would be defining the order in which words and symbols might make up a | ||
| language and provide meaning. This is when Perl's grammar system fits | ||
| perfectly. | ||
| Grammars parse strings and return data structures from those strings. Grammars can |
There was a problem hiding this comment.
This explains what grammars are. I like the original better in that it provides a use-case for why grammars came about in the first place.
There was a problem hiding this comment.
I can switch back.
| strings of some kind that you need to bring order to, or interpret, grammars | ||
| give you some great tools to make it easier. | ||
| If you have strings to tame or interpret, grammars provide the | ||
| tools to do the job. |
There was a problem hiding this comment.
I thought that is what regex is for?
There was a problem hiding this comment.
I know. :) maybe an adjective phrase.
If you have overly complicated strings to tame or interpret, grammars provide the tools to do the job.
| Grammars provide a way to define how you want to examine a string using regular | ||
| expressions, and you can group these regular expressions together to provide | ||
| even more meaning. | ||
| When working with HTML, you could define a grammar to recognize HTML tags, both |
There was a problem hiding this comment.
This paragraph belongs in the "when would I use grammars" section. Feels out of place. maybe prepend "For example, " like in the original.
There was a problem hiding this comment.
I'll take a look at this.
| object back that contained 'clever_text_keyword' keyed by the name of 'thingy' | ||
| in your match object. These can grow much more complex, as your needs require, | ||
| as you might imagine. | ||
| in your match object. |
There was a problem hiding this comment.
Show, don't tell. Can we see a console output of what this would look like?
> my $match = My::Gram.parse( ' clever_text_keyword 8=_.432432jfd' )
> say $match
> thingy => 'clever_text_keyword'
| @@ -104,50 +81,45 @@ will be keyed with the same name as the method you chose to name it. | |||
| } | |||
There was a problem hiding this comment.
add # .* indicates that we are looking for <thingy> first and then any number of whatevers can come after it
and add # remember that token ignores whitespace
| adding a question mark for the grouped '/' and I<data> components of the TOP | ||
| token, to indicate their optional nature, just like a normal regex. So now we | ||
| have: | ||
| means the grammar will fail to match if we try to parse a create URI. To avoid |
There was a problem hiding this comment.
show example:
> my $match = REST.parse('/product/create/');
> say $match;
> (Any)
| the match object, otherwise it is absent. | ||
| assigned to the parent proto token. If the special <sym> token was employed and | ||
| formed all or part of the actual match, then it's preserved as a sub-level in | ||
| the match object, otherwise it's absent. |
There was a problem hiding this comment.
How would you access this sub-level from the match object? example?
| grammars. A lot of the time you'll be happy using grammars just on their own. | ||
| But when you need to process some of those strings further, you can plug in the | ||
| expansion module. | ||
| grammars. A lot of the time you'll be happy using grammars all by their own. |
There was a problem hiding this comment.
Options to choose from:
- A lot of the time you'll be happy using grammars all on their own.
- A lot of the time you'll be happy using grammars all by themselves.
- A lot of the time you'll be happy using grammars just on their own.
| If you I<name your action methods with the same name as your grammar methods> | ||
| (tokens, regexes, rules), then when your grammar methods match, your action | ||
| method with the same name will get called automatically. The method will also be | ||
| passed the corresponding match object (represented by the $/ variable). |
There was a problem hiding this comment.
| @@ -621,16 +559,14 @@ And this is the grammar and grammar actions that got us there, to recap: | |||
| } | |||
| =end code | |||
|
|
|||
There was a problem hiding this comment.
We should also include an alternate version that splits the data into smaller pieces by just using the grammar methods. The whole time that was in my mind like "why do we need an action for this"? So perhaps we can quell questions by just including the alternate as a side note.
|
@tbrowder++ approved, hence merged. Thanks for the contribution! |
Would invite feedback, suggestions for changes.