{"id":21723145,"url":"https://github.com/theiskaa/mate","last_synced_at":"2025-04-12T22:05:01.233Z","repository":{"id":45891728,"uuid":"421074628","full_name":"theiskaa/mate","owner":"theiskaa","description":"A simple and lightweight arithmetic expression interpreter","archived":false,"fork":false,"pushed_at":"2024-01-11T19:27:12.000Z","size":225,"stargazers_count":21,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T22:04:44.561Z","etag":null,"topics":["interpreter","math","parser"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/mate-rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theiskaa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-10-25T15:12:44.000Z","updated_at":"2025-03-22T10:31:43.000Z","dependencies_parsed_at":"2024-01-12T00:15:31.212Z","dependency_job_id":null,"html_url":"https://github.com/theiskaa/mate","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiskaa%2Fmate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiskaa%2Fmate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiskaa%2Fmate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiskaa%2Fmate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theiskaa","download_url":"https://codeload.github.com/theiskaa/mate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637771,"owners_count":21137538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interpreter","math","parser"],"created_at":"2024-11-26T02:37:19.588Z","updated_at":"2025-04-12T22:05:01.212Z","avatar_url":"https://github.com/theiskaa.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n \u003cimg width=\"350\" src=\"https://user-images.githubusercontent.com/59066341/138941465-a4354274-3976-4571-bdcd-df031d7d4761.png\" alt=\"Package Logo\"\u003e\n \u003cbr\u003e\n \u003ca href=\"https://github.com/theiskaa/mate/blob/main/LICENSE\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-red.svg\" alt=\"License: MIT\"/\u003e\n \u003c/a\u003e\n\u003c/p\u003e\n\nMate is a library designed for parsing and calculating arithmetic expressions inputted as strings. It utilizes a Lexer structure, similar to those found in interpreted programming languages, to parse string input into a token list. The Calculator structure is then used to compute the final result from this token list. A general wrapper structure is also implemented that encapsulates both the Lexer and Calculator, simplifying the process of calculating arithmetic expression results without the need for manual parsing and calculation.\n\n**Note**: This project serves as a demonstration and is not intended for production use. It represents my initial steps in learning to create a programming language.\n\n# Usage\n\nThis crate is available on [crates.io](http://crates.io/crates/mate-rs) and can be added to your project's dependencies in your `Cargo.toml` file.\n```toml\n[dependencies]\nmate-rs = \"0.1.4\"\n```\n\n## Example: Using `Mate`\n\n`Mate` is a general wrapper structure for `Lexer` and `Calculator`. It provides a single method for calculating results from string input.\n\n```rust\nuse mate_rs::mate::Mate;\n\nlet result = Mate::calculate(\"6 * 7\");\nmatch result {\n    Ok(v) =\u003e assert_eq!(v, 42.0),\n    Err(_) =\u003e {\n        // Handle error ...\n    }\n};\n```\n\n## Example: Using `Lexer` and `Calculator`\n\n`Lexer` is the primary structure that parses string input into a token list. `Calculator` is used to compute the final result from the `Lexer`'s output.\n\n```rust\nuse mate_rs::{calculator::Calculator, lexer::Lexer};\n\nlet input = \"[ (2 + 5) * (5 - 9 + (8 - 5)) ] + 35\";\nlet tokens = Lexer::lex(input.clone()).unwrap(); // Error handling should also be implemented\n```\n\n\u003cdetails close\u003e\n\u003csummary\u003eView the generated token tree\u003c/summary\u003e\n\u003cbr\u003e\n\u003cpre\u003e\n\u003ccode\u003e\n// The generated tokens will resemble the following:\n//\n//   Token(\n//     type: SUBEXP,\n//     tokens: [\n//          Token(\n//            type: SUBEXP,\n//            tokens: [\n//                 Token(type: NUMBER,  literal: \"2\")\n//                 Token(type: PLUS,    literal: \"+\")\n//                 Token(type: NUMBER,  literal: \"5\")\n//            ],\n//          ),\n//          Token(type: PRODUCT, literal: \"*\"),\n//          Token(\n//            type: SUBEXP,\n//            tokens: [\n//                 Token(type: NUMBER,  literal: \"5\")\n//                 Token(type: MINUS,   literal: \"-\")\n//                 Token(type: NUMBER,  literal: \"9\")\n//                 Token(type: PLUS,    literal: \"+\")\n//                 Token(\n//                   type: SUBEXP,\n//                   tokens: [\n//                        Token(type: NUMBER,  literal: \"8\")\n//                        Token(type: PLUS,    literal: \"-\")\n//                        Token(type: NUMBER,  literal: \"5\")\n//                   ],\n//                 ),\n//            ],\n//          ),\n//     ],\n//   ),\n//   Token(type: PLUS,    literal: \"+\")\n//   Token(type: NUMBER,  literal: \"35\")\n\u003c/code\u003e\n\u003c/pre\u003e\n\u003c/details\u003e\n\n```rust\n// The result is calculated from the tokens using the X/O/Y algorithm.\n//\n//  ╭────────╮ ╭───────────╮ ╭────────╮\n//  │ NUMBER │ │ OPERATION │ │ NUMBER │\n//  ╰────────╯ ╰───────────╯ ╰────────╯\n//       ╰───╮       │        ╭───╯\n//           ▼       ▼        ▼\n//           X  [+, -, *, /]  Y\n//\nlet result = Calculator::calculate(tokens, input.clone());\n```\n\n---\n\n# How it Works\nMate primarily consists of two main structures: [Lexer] and [Calculator]. The [Lexer] structure is responsible for parsing and interpreting the given string expression, while the [Calculator] structure calculates the final result from the parsed tokens.\n\n## Lexer\nThe Lexer iterates through the given input string, reading and converting each character into a [Token] structure. The main types of tokens include:\n- `ILLEGAL` - Represents an illegal character.\n- `NUMBER` - Represents a number.\n- `MINUS`, `PLUS`, `PRODUCT`, `DIVIDE`, `PERCENTAGE`, `POWER` - Represents operations.\n- `LPAREN`, `RPAREN` - Represents parentheses.\n- `LABS`, `RABS` - Represents absolute values.\n- `SUBEXP` - Represents sub-expressions, which are expressions inside parentheses, absolute values, or combinations of division and multiplication.\n\nThe Lexer's `lex` function converts each character into one of these tokens. It groups tokens related to multiplication or division operations into a single sub-expression to maintain the correct operation priority. It also nests parentheses, absolute values, and powers using a custom level-to-expression algorithm.\n\nThe level-to-expression algorithm is a mapping algorithm that maps a specific expression to its nesting level.\n\nFor example, given the token list `(2 + 5) : (5 - 9 / (8 - 5))`, the generated result will be:\n\n\u003cimg width=\"500\" alt=\"mate\" src=\"https://user-images.githubusercontent.com/59066341/192025304-220c58eb-8bbe-4820-bd6a-5f18b5b5758b.png\"\u003e\n\nThis approach ensures the correct operation priority is maintained.\n\n## Calculator\n\nThe Calculator takes the parsed token list and calculates the final result. It uses a custom `X/O/Y` algorithm, also known as `X/OPERATION/Y`, where `X` and `Y` are numbers, and `O` is an operation. If `X` or `Y` cannot be obtained, they are taken as zero.\n```\n╭────────╮ ╭───────────╮ ╭────────╮\n│ NUMBER │ │ OPERATION │ │ NUMBER │\n╰────────╯ ╰───────────╯ ╰────────╯\n     ╰───╮       │        ╭───╯\n         ▼       ▼        ▼\n         X  [+, -, *, /]  Y\n```\n\n---\n\n# Syntax\n\nThe syntax of `Mate` is designed to be as simple and basic as possible. It follows the plain-text mathematics syntax with a few customizations. Here are some examples:\n\n### Addition and Subtraction\n`2 + 5` and `2 - 5` are valid syntaxes. (in `x \u003coperation\u003e y` where x and y could be `NUMBER` or `SUBEXP`).\n\n### Multiplication, Division, and Percentage\n`4 * 2`, `4 / 2`, and `4 % 2` are valid syntaxes. (in `x \u003coperation\u003e y` where x and y could be `NUMBER` or `SUBEXP`). Also, `4(10 / 2)` or `4(2)` are valid syntaxes for multiplication.\n\n### Power\n`4 ^ 2` is a valid syntax. (in `x \u003coperation\u003e y` where x and y could be `NUMBER` or `SUBEXP`). Continuous powers are also accepted: `4 ^ 2 ^ 3`, which will be automatically converted to `4 ^ (2 ^ 3)`.\n\n### Parentheses\n`(2 * 5)` is a valid syntax. (in `x \u003coperation\u003e y` where x and y could be `NUMBER` or `SUBEXP`). Nested parentheses expressions are also accepted: `(2 * ((5 * 2) / (9 - 5)))`.\n\n### Absolute Values\n`[2 - 12]` is a valid syntax. (in `x \u003coperation\u003e y` where x and y could be `NUMBER` or `SUBEXP`). Nested absolute-value expressions are also accepted: `[7 - 14] * [5 - 9 / [5 - 3]]`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiskaa%2Fmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheiskaa%2Fmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiskaa%2Fmate/lists"}