{"id":16302213,"url":"https://github.com/kaiepi/ra-annotations","last_synced_at":"2025-07-13T00:34:39.347Z","repository":{"id":133444424,"uuid":"527545091","full_name":"Kaiepi/ra-annotations","owner":"Kaiepi","description":"Thread-safe static buffer","archived":false,"fork":false,"pushed_at":"2022-08-26T06:40:20.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T05:55:16.112Z","etag":null,"topics":["data","type"],"latest_commit_sha":null,"homepage":"","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kaiepi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-22T12:00:31.000Z","updated_at":"2022-08-22T20:05:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"c062efce-79d1-4322-8b01-7374fc821406","html_url":"https://github.com/Kaiepi/ra-annotations","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Kaiepi/ra-annotations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kaiepi%2Fra-annotations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kaiepi%2Fra-annotations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kaiepi%2Fra-annotations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kaiepi%2Fra-annotations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kaiepi","download_url":"https://codeload.github.com/Kaiepi/ra-annotations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kaiepi%2Fra-annotations/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265075543,"owners_count":23707509,"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":["data","type"],"created_at":"2024-10-10T20:56:45.655Z","updated_at":"2025-07-13T00:34:39.060Z","avatar_url":"https://github.com/Kaiepi.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build Status](https://github.com/Kaiepi/ra-annotations/actions/workflows/test.yml/badge.svg)\n\nNAME\n====\n\nannotations - Thread-safe static buffer\n\nSYNOPSIS\n========\n\n```raku\nuse v6.e.PREVIEW;\n\nmy constant LATIN = 'a'..'z';\n\nmodule Upper {\n    use annotations \u003cdeclare symbolic class\u003e;\n    # We may now declare a class with a symbolic object buffer associated with\n    # it. This can be retrieved by parameterizing ANN with our type object,\n    # which is typically knowable at compile-time.\n\n    role Alphabet[@LOOKUP is raw] is repr\u003cUninstantiable\u003e {\n        # The annotated operator makes some allocations in an annotation's ANN\n        # buffer eagerly given some Str-coercive objects. These become IntStr:D\n        # symbols, which is to say they're a name and a position in the buffer\n        # for this mixin. Because we take care of this immediately, this can\n        # act as our compile-time check for whether or not we really are\n        # composing an annotation. Such allocating in ANN is thread-safe.\n        my @SYMBOLS := $?CLASS annotate @LOOKUP;\n\n        # The bare slots can be fetched by ANN's list method given these\n        # symbols. Because these carry containers regardless of whether or not\n        # a value is being stored, this can always be assigned to dynamically.\n        method alphabet(::?CLASS: --\u003e List:D) {\n            ANN[$?CLASS].list: :of(@SYMBOLS)\n        }\n\n        # Likewise, these symbols can form the keys of a map by the ANN's hash\n        # method.\n        method dictionary(::?CLASS: --\u003e Map:D) {\n            ANN[$?CLASS].hash: :of(@SYMBOLS)\n        }\n\n        # This will find a letter given the key of a booked symbol.\n        method translate(::?CLASS: Str:D --\u003e Str) { ... }\n    }\n\n    annotation Half does Alphabet[LATIN] is repr\u003cUninstantiable\u003e {\n        CHECK $?CLASS.alphabet = 'A'..'Z';\n\n        my %DICTIONARY := $?CLASS.dictionary;\n\n        method translate(::?CLASS: Str:D $letter --\u003e Str) {\n            %DICTIONARY.AT-KEY: $letter\n        }\n    }\n\n    annotation Full does Alphabet[LATIN] is repr\u003cUninstantiable\u003e {\n        CHECK $?CLASS.alphabet = 'Ａ'..'Ｚ';\n\n        my %DICTIONARY := $?CLASS.dictionary;\n\n        method translate(::?CLASS: Str:D $letter --\u003e Str) {\n            %DICTIONARY.AT-KEY: $letter\n        }\n    }\n}\n\n# Despite the inner alphabet list being static, public, mutable state by\n# technicality, its inner Binder slots each only respects its first assignment.\nput Upper::Full.alphabet = Upper::Half.alphabet; # OUTPUT:\n# Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ\nput Upper::Full.translate: 'a'; # OUTPUT:\n# Ａ\n\n# But because we can achieve all this with static input alone, we can write a\n# cheaper annotation.\nmodule LowerPsychUpper {\n    use annotations \u003cdeclare direct class\u003e;\n    # Now the ANN buffer is purely a buffer. Direct annotations' ANN buffer is\n    # a lower level construct compared to before; because we get references\n    # over symbols, we generally need to track any value bound ourselves.\n\n    annotation Full is repr\u003cUninstantiable\u003e {\n        # Note the RW array this time around.\n        my constant @ALPHABET = $?CLASS annotate ['ａ'..'ｚ'];\n\n        my constant %DICTIONARY = Map.new: LATIN Z=\u003e @ALPHABET;\n\n        method alphabet(::?CLASS: --\u003e List:D) {\n            @ALPHABET\n        }\n\n        method dictionary(::?CLASS: --\u003e Map:D) {\n            %DICTIONARY\n        }\n\n        method translate(::?CLASS: Str:D $letter --\u003e Str) {\n            %DICTIONARY{$letter}\n        }\n    }\n}\n\n# Unlike before, the RW containers provided by the RW array we annotated are\n# preserved, so an assignment will carry through.\nput LowerPsychUpper::Full.alphabet = Upper::Full.alphabet; # OUTPUT:\n# Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ\nput LowerPsychUpper::Full.translate: 'z'; # OUTPUT:\n# Ｚ\n\n# In this example, we have code resembling what's possible to write with OUR.\n# Unlike a Stash in a WHO or a PseudoStash, ANN errs more toward order and\n# immutability, but deconts of a Scalar are cheaper than those of a wrapper\n# Proxy. An OUR-scoped value skips a call we need otherwise on top of this, and\n# would thus be more efficient if the WHO Stash's inherent mutability is OK.\n```\n\nDESCRIPTION\n===========\n\n`annotations` is a collection of containers in a package trench coat. Through `MetamodelX::AnnotationHOW`, a `Positional` or `Associative` container may be associated with any kind of type, regardless of whether or not it actually can support stashing. These can be retrieved with `ANN`, and appended to via the infix `=`, `annotate`, and `graffiti` operators (see `t/02-direct.t` for an example of `graffiti`).\n\nImporting `annotations` can either create an `annotation` declarator with `\u003cdeclare\u003e` or override another (e.g. `\u003crole\u003e`) with `\u003csupersede\u003e` (though this produces an erroneous deprecation warning as of v2020.07). As demonstrated, the `\u003cdirect\u003e` and `\u003csymbolic\u003e` arguments determine the mode of assignment to a package's `ANN`. Finally, a package declarator must be provided in order to retrieve its HOW.\n\nAUTHOR\n======\n\nBen Davies (Kaiepi)\n\nCOPYRIGHT AND LICENSE\n=====================\n\nCopyright 2022 Ben Davies\n\nThis library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaiepi%2Fra-annotations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaiepi%2Fra-annotations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaiepi%2Fra-annotations/lists"}