Feat/base64 predicate

[ccamel]

Introduces the base64_encoded/3 predicate to the logic module, strongly inspired by the library(base64) from SWI-Prolog.

Supports both encoding and decoding modes, along with options for output format (as(atom) or as(string)), padding, and charset (classic or url).

Summary by CodeRabbit

• New Features

  • Introduced Base64 encoding and decoding functionality accessible via a new predicate, supporting multiple input types and customizable options such as charset, padding, and output format.
  • Enhanced system configuration to accommodate advanced encoding capabilities.

• Tests

  • Added comprehensive test scenarios to validate both successful Base64 transformations and proper error handling for invalid inputs.

[coderabbitai]

Walkthrough

This pull request adds a new predicate "base64_encoded/3" to the interpreter’s registry. It implements the predicate in the encoding module to perform Base64 encoding and decoding with multiple unification signatures and configurable options. Additionally, it introduces new atom definitions for charset and boolean types, and incorporates a comprehensive feature test file that validates both successful and error scenarios for the predicate.

Changes

Files	Change Summary
x/logic/interpreter/registry.go	Added a new registry entry mapping "base64_encoded/3" to predicate.Base64Encoded.
x/logic/predicate/encoding.go	Introduced the Base64Encoded predicate function with support for three unification signatures, including internal converters (forwardConverter and backwardConverter) and a helper (getBase64Encoding) for processing Base64 encoding options.
x/logic/predicate/features/...base64_encoded_3.feature	Added a feature file containing scenarios for encoding and decoding operations, including tests for various options, output types, and error handling.
x/logic/prolog/atom.go, x/logic/prolog/error.go	Added new atom definitions: AtomCharset and AtomBoolean in atom.go, and AtomTypeBoolean in error.go to support the predicate options and type handling in the Prolog engine.

Sequence Diagram(s)

sequenceDiagram
    participant U as User
    participant I as Interpreter
    participant P as Base64Encoded Predicate
    participant C as Converter

    U->>I: Invoke base64_encoded/3 with parameters
    I->>P: Lookup predicate from registry
    alt Encoding operation
        P->>C: Call forwardConverter with plain input and options
    else Decoding operation
        P->>C: Call backwardConverter with encoded input and options
    end
    C-->>P: Return processed result or error
    P-->>I: Return result wrapped in Promise
    I-->>U: Deliver final result

Loading

Possibly related PRs

• Feat/expose database predicates #812: Introduced similar predicate functionality for Base64 operations, closely related to the new Base64Encoded integration.
• Feat/more predicates #783: Modified the registry by adding new predicate mappings, directly related to the inclusion of "base64_encoded/3".

Suggested reviewers

• bdeneux
• amimart

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (1.64.8)

Error: you are using a configuration file for golangci-lint v2 with golangci-lint v1: please use golangci-lint v2
Failed executing command with error: you are using a configuration file for golangci-lint v2 with golangci-lint v1: please use golangci-lint v2

---

📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between da6a217 and 02b8bb7.

⛔ Files ignored due to path filters (26)

• docs/predicate/base64_encoded_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/bech32_address_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/block_header_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/block_height_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/block_time_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/chain_id_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/consult_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/crypto_data_hash_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/current_output_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/did_components_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/ecdsa_verify_4.md is excluded by !docs/predicate/**/*.md
• docs/predicate/eddsa_verify_4.md is excluded by !docs/predicate/**/*.md
• docs/predicate/hex_bytes_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/json_prolog_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/json_read_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/json_write_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/open_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/open_4.md is excluded by !docs/predicate/**/*.md
• docs/predicate/read_string_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/read_term_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/retract_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/source_file_1.md is excluded by !docs/predicate/**/*.md
• docs/predicate/string_bytes_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/term_to_atom_2.md is excluded by !docs/predicate/**/*.md
• docs/predicate/uri_encoded_3.md is excluded by !docs/predicate/**/*.md
• docs/predicate/write_term_3.md is excluded by !docs/predicate/**/*.md

📒 Files selected for processing (5)

• x/logic/interpreter/registry.go (1 hunks)
• x/logic/predicate/encoding.go (1 hunks)
• x/logic/predicate/features/base64_encoded_3.feature (1 hunks)
• x/logic/prolog/atom.go (2 hunks)
• x/logic/prolog/error.go (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

`**/*.go`: Review the Go code, point out issues relative to principles of clean code, expressiveness, and performance.

**/*.go: Review the Go code, point out issues relative to principles of clean code, expressiveness, and performance.

• x/logic/prolog/error.go
• x/logic/interpreter/registry.go
• x/logic/prolog/atom.go
• x/logic/predicate/encoding.go

🧬 Code Definitions (2)

x/logic/interpreter/registry.go (1)

x/logic/predicate/encoding.go (1)

• Base64Encoded (54-115)

x/logic/predicate/encoding.go (4)

x/logic/prolog/option.go (2)

• GetOptionWithDefault (60-69)
• GetOptionAsAtomWithDefault (73-86)

x/logic/prolog/atom.go (7)

• AtomAs (7-7)
• AtomEncoding (19-19)
• AtomUtf8 (57-57)
• AtomCharset (37-37)
• AtomPadding (35-35)
• AtomTrue (55-55)
• AtomFalse (23-23)

x/logic/prolog/text.go (2)

• TextTermToString (71-93)
• StringToCharacterListTerm (101-108)

x/logic/prolog/unify.go (1)

• UnifyFunctionalPredicate (82-99)

⏰ Context from checks skipped due to timeout of 90000ms (1)

• GitHub Check: test-go

🔇 Additional comments (9)

x/logic/prolog/atom.go (2)

36-37: New atom definition for the charset encoding option looks good.

The AtomCharset is properly defined with a clear comment explaining its purpose, consistent with the project's standard for atom definitions.

---

52-53: New atom definition for boolean type is correctly implemented.

The AtomBoolean is properly defined with an appropriate comment that explains its purpose, following the established pattern for atom definitions in this file.

x/logic/prolog/error.go (1)

54-55: Boolean type atom follows the established pattern.

The new AtomTypeBoolean variable is correctly defined with a descriptive comment, maintaining consistency with other type atom declarations in this file.

x/logic/interpreter/registry.go (1)

128-128: Base64 encoding predicate registration is properly implemented.

The new base64_encoded/3 predicate is correctly registered in the ordered map, linking to the predicate.Base64Encoded function implementation. The addition follows the established pattern for predicate registration in this file.

x/logic/predicate/features/base64_encoded_3.feature (1)

1-393: Comprehensive test coverage for the base64_encoded/3 predicate.

The feature file provides thorough testing of the new predicate functionality, covering both successful encoding/decoding operations and error handling scenarios. The tests include:

1. Encoding with default options
2. Custom output formats (string/atom)
3. Padding control
4. URL-safe character set variant
5. Comprehensive error handling for invalid inputs

The scenarios are well-documented with clear explanations, and the @great_for_documentation tags appropriately highlight key usage examples.

x/logic/predicate/encoding.go (4)

4-17: Imports and atom definitions look consistent

The choice of introducing the base64 import and creating new atom constants for charset and output types is logical and consistent with the existing conventions.

---

19-53: Comprehensive documentation

The docstring thoroughly explains usage, parameters, options, and references to RFC 4648. This level of clarity promotes better maintainability and straightforward onboarding for other contributors.

---

54-115: Robust predicate implementation with clear forward/backward converters

The separation of concerns via forwardConverter and backwardConverter is elegant, providing clarity for encoding and decoding flows. Consider reviewing coverage for handling unexpected edge cases, such as invalid Base64 inputs or unsupported encodings, to further boost reliability.

Would you like me to suggest additional test cases covering corrupt Base64 data or unusual character sets?

---

117-147: Ensure intended behavior for URL-safe variant with padding

While the URL-safe encoding with optional padding is valid, usage can vary across different consumers. If this is intended for broad interoperability, confirm no conflicts arise from partially padded outputs or unpadded outputs.

Feel free to let me know if you want a helper script to test URL-safe Base64 with and without padding for potential client interoperability issues.

✨ Finishing Touches

• 📝 Generate Docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai plan to trigger planning for file edits and PR creation.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[codecov]

Codecov Report

Attention: Patch coverage is 97.40260% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
x/logic/predicate/encoding.go	97.40%	2 Missing ⚠️

@@            Coverage Diff             @@
##             main     #921      +/-   ##
==========================================
- Coverage   45.08%   38.49%   -6.59%     
==========================================
  Files         113      113              
  Lines        6399     6476      +77     
==========================================
- Hits         2885     2493     -392     
- Misses       3379     3863     +484     
+ Partials      135      120      -15     

Files with missing lines	Coverage Δ
x/logic/interpreter/registry.go	0.00% <ø> (-81.82%)	⬇️
x/logic/prolog/error.go	0.00% <ø> (ø)
x/logic/predicate/encoding.go	91.74% <97.40%> (+13.61%)	⬆️

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.