This is the back-end version of the Love Geometry assignment, which you may solve and present your solution in order to [[showcase relevant expertise]] in the context of our [[join us#The Process|recruitment process]]. We consider [[Love Geometry (back-end version)#Step 1. The Language of Love and Destruction|Step 1]] and [[Love Geometry (back-end version)#Step 2. Show Me Your Love|Step 2]] to be the bare minimum required to assess your expertise. The rest of the steps are optional. While each step allows to showcase some valuable traits, it's ok not to complete all of them. Please ensure to carefully read through the [[solve an assignment#Submission Requirements|submission requirements]] and the [[showcase relevant expertise#HOW to showcase?|entire process]] of presenting and discussing the solution to this assignment. --- ## Intro >Dive into [PEG](https://en.wikipedia.org/wiki/Parsing_expression_grammar) by building a simple language for a complex phenomena. The world of back-end engineering is a universe of machines talking with machines about what other machines just did or should do in order to produce meaningful value for people. In order for non-engineers to interact with this world, a translator is needed. That's where [GUIs](https://en.wikipedia.org/wiki/Graphical_user_interface) come in. How can we help humans communicate with machines without a translator? Sometimes it’s better to use something less powerful than a high-level programming language, something easier to grasp, something like [DSL](https://en.wikipedia.org/wiki/Domain-specific_language). This assignment invites you to create a dummy language to describe relationships between people. ## Step 0. Pick Your Tools Take a look at [peggy.js](https://peggyjs.org/). It's a Javascript parser for [parsing expression grammars](https://www.wikiwand.com/en/Parsing_expression_grammar), which is very similar to context-free grammars (aka regular expressions). For `Python` we may suggest [pyPEG](https://fdik.org/pyPEG/). If you are looking for a `PHP` library, then [PHP PEG](https://github.com/hafriedlander/php-peg) may be a good choice. You are free to use something else, if you so desire. ## Step 1. The Language of Love and Destruction >Bob has a crush on Alice. Is it mutual? Get acquainted with our concepts of PEG, and build a parser for love stories to find out. Imagine a dummy language, describing relationships among people: ``` A loves B but B hates A. A hates B, A loves D while B loves C and D hates A. A loves B, B loves A and B loves D. A loves B but B hates A D loves B and C loves A. ``` We’ve just described a love dynamics among people. Each sentence represents a state in an evolving story. Note that there are **multiline** sentences (like the last one)! Let’s say we wanted to write a parser for this language, returning, for each line, a structure for the relationships of the people in it, e.g.: ```js [ { 'A': { 'loves': ['B'] }, 'B': { 'hates': ['A'] } }, { 'A': { 'hates': ['B'], 'loves': ['D'] }, 'B': { 'loves': ['C'] }, 'D': { 'hates': 'A' } } ] ``` This table represents the first two lines of our story. Without giving you a formal definition of this language, we want you to design a grammar articulate enough to encapsulate its spirit. At this stage, we do not ask for any user interface. Instead, we want the parser to be implemented as a module, and covered by test cases. You can use any testing framework you’d like. You should provide a description for each of your test cases. ### Completion Checklist - [ ] PEG parser for the love story language - [ ] Parser unit tests - [ ] `README.md` including installation and running manuals ### On the Meaning of Love Let’s shed some light on the terms used throughout this assignment. A _state of love_, the _love case,_ or the _situation of love,_ is the order of things described in one sentence. We can think of it as a snapshot of relationships. A _love story_ is a sequence of love states. ## Step 2. Show Me Your Love >Create an ecosystem for your language. Build an API server to parse love stories. First, we want you to create a simple web application with one API endpoint which receives a love story and responds with the parsed structure. Pick whatever framework you’d like. Next, you’ll have to write a simple client library that talks to that endpoint and parses written love stories into their structural representations. There should be a minimal error reporting with HTTP codes and error descriptions in case the client sends invalid love statements. You can present your solution in three ways: 1. Make a CLI tool that uses the client and communicates with the love story server, retrieving parsed stories. 2. Create a simple [Jupyter Notebook](http://jupyter.org/) with a piece of the code which talks to the love story server and prints responses in an easy, readable way. 3. Build a simple web page with a text area in which users can write their love stories, and obtain a parsed story through the click of a button. Nothing fancy is required, a plain AJAX, for example, would work just fine. Choose the option that fits you best. From now on, we will refer to this part of the solution as `Presentation UX`. Make sure that you've provided enough examples to showcase your work. ### Completion Checklist - [ ] Server application that parses love stories - [ ] Client library that talks to the server - [ ] Presentation UX - [ ] A set of sample love stories - [ ] `README.md` including details on how to start and use the app This part of the assignment, together with [[Love Geometry (back-end version)#Step 1. The Language of Love and Destruction|Step 1]], is the minimum requirement for us to [[showcase relevant expertise|evaluate your expertise]]. ### More Summits Ahead We do have a few more challenges for you, if you feel like going :) There’s a chance your solution might contain some errors. One never really knows! Completing additional steps will grant higher confidence in your results. ## Step 3. Find the Cheater (optional) >Sometimes people don’t know what they want. Sometimes they lie. Love is divine and dangerous at the same time. Analyse love stories and find their contradictions. Although this assignment is optional, it may come in handy at later stages. It may also give you some perspective on the design of your DSL. With reference to [[Love Geometry (back-end version)#Step 1. The Language of Love and Destruction|Step 1]], the syntax does not stop us from writing things like: ``` A loves B but A hates B. A loves B, A loves B, A loves B. A loves A. ``` What are some of the additional constrains we should apply to the language semantics? Define those constrains, and describe them, either in the [`README.md`](http://readme.md/). Implement a validator that checks parsed structures and reports error messages when a user writes a meaningless state of love. You could also enrich the grammar with some checks, but the parser should not swallow errors (e.g. if users do something you consider to be wrong, they should receive an error). The semantic check can be implemented in the parser library or at the server application level, up to you. However, we want to be able to receive the unchecked (original) responses. Please, [avoid putting the logic in the controller](https://www.hughgrigg.com/posts/keep-controllers-thin/). ### Completion Checklist - [ ] Implement semantic validation at the parser or at the server application level - [ ] Make the parser run without checks if needed - [ ] Propagate errors to the client - [ ] Document your decisions - [ ] Write unit tests for your rule checker - [ ] Add or update the code in the presentation UX to test your solution ## Step 4. Circles of Affection (optional) >Have you ever been a part of a love triangle? How about a love pentagon? A love polytope? Anyone? Try out some graph theory and find circles of affection in love stories. Consider a state of love with the following circles of affection: ``` A loves B, B loves C and C loves A. A hates B while B hates A. A loves A. ``` In the first sentence we have a traditional love triangle, while the second describes mutual loathing. The third sentence represents high self-esteem. Have you, by any chance, forbidden that kind of relations in [[Love Geometry (back-end version)#Step 3. Find the Cheater (optional)|Step 3]]? You may want to reconsider your decision. Or not. Up to you really. In order to complete this exercise you have to design and implement an algorithm that finds all circles of affection in a given sate of love. We want you to create an API endpoint which responses with a list of such circles for a given love story, to update the client library, and to extend your presentation UX in order to test this exercise. The algorithm itself can be implemented at the level of the parser library or as a part of the application. Whatever you do, please [avoid putting the logic inside the controller](https://www.hughgrigg.com/posts/keep-controllers-thin/). ### Completion Checklist - [ ] Implement the algorithm that searches for circles of affection - [ ] Write unit tests for your algorithm - [ ] Add the API endpoint - [ ] Update the client library - [ ] Add or update your presentation UX to test your solution ## Step 5. The Matrix of Love (optional) >It’s time to talk about relationships. The mathematical ones, the ones that govern the relational databases. Transform your love stories into tables. Let’s consider the following situation: ``` Lyubomyr loves Ron, Ron hates Lyubomyr Vasyl hates Alice, Alice hates Vasyl Ulices loves Alice, Alice loves Ulices Mary loves Vasyl Ulises hates Theodoric. ``` For this instance, the corresponding table would look like the following: | | Ron | Alice | Mary | Theodoric | |---------|-------|-------|-------|-----------| | Vasyl | | - | ?/+ | | | Lyubomyr | +/- | | | -/? | | Ulises | | + | | | The table is good, but the textual description is not elegant. If we add a special keyword to describe mutual affection, the description becomes: ``` Lyubomyr loves Ron, Ron hates Lubomyr Vasyl mutually hates Alice Ulices mutually loves Alice Mary loves Vasyl Ulises hates Theodoric. ``` Much better! To complete this assignment, serve an HTML page with a form consisting of a text area field for a love story, and a submit button. Once pressed, the button should render a page with love representation tables corresponding to the love story the user wrote. If you've already chosen a web page as your presentation UX, just add another tab, or create a new one. You can use AJAX requests, reload the page with the submitted GET, or POST parameters. It’s completely up to you. In case of wrong input, the corresponding errors should be displayed. To earn all the available credits, you will also have to introduce the `mutually` keyword to the love language parser. ### The Love Matrix Behaviour To clarify how the table should work, let's look at some examples. Say we added, in addition to the existing text, the following: ``` ... Ulises mutually loves Mike ... ``` That means we have to add a new column, e.g.: | | Ron | Alice | Mary | Theodoric | Mike | |---------|-----|-------|------|-----------|------| | Vasyl | | - | ?/+ | | | | Lyubomyr | +/- | | | -/? | | | Ulises | | + | | | + | Now, if we will strip away `Mary loves Vasyl` from the text, we will get: ``` Lyubomyr loves Ron, Ron hates Lyubomyr Vasyl mutually hates Alice Ulices mutually loves Alice Ulises mutually loves Mike Ulises hates Theodoric. ``` “Mary” disappears, and the corresponding column is removed from the table: | | Ron | Alice | Theodoric | Mike | | ---- | ---- | ---- | ---- | ---- | | Vasya | | - | | | | Lyubomir | +/- | | -/? | | | Ulises | | + | | + | ### Completion Checklist - [ ] Create a web page with a text area for a love story, and a submit button - [ ] Render love representation tables for a given submitted story - [ ] Write unit tests for the graph-table converter - [ ] Document your solution in the `README.md` - [ ] (for the super bonus points!) Add the `mutual` keyword to the love story language --- Than you for getting here 🙃 Please ensure to carefully read through the [[solve an assignment#Submission Requirements|submission requirements]] and the [[showcase relevant expertise#HOW to showcase?|entire process]] of presenting and discussing the solution to this assignment. Looking forward to the next step 🙌