{"id":22066253,"url":"https://github.com/modlfo/pla","last_synced_at":"2025-05-13T01:55:15.699Z","repository":{"id":74855077,"uuid":"61573167","full_name":"modlfo/pla","owner":"modlfo","description":"Pla is a simple library and ppx syntax extension to create composable templates based on verbatim strings","archived":false,"fork":false,"pushed_at":"2022-11-01T07:11:33.000Z","size":181,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-13T01:55:07.491Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modlfo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-06-20T19:06:14.000Z","updated_at":"2023-11-16T13:51:53.000Z","dependencies_parsed_at":"2023-05-25T00:15:49.774Z","dependency_job_id":null,"html_url":"https://github.com/modlfo/pla","commit_stats":{"total_commits":47,"total_committers":1,"mean_commits":47.0,"dds":0.0,"last_synced_commit":"c48b01bad841c8656824b467f3a35132804d3e6d"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlfo%2Fpla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlfo%2Fpla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlfo%2Fpla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlfo%2Fpla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modlfo","download_url":"https://codeload.github.com/modlfo/pla/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253856640,"owners_count":21974577,"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":[],"created_at":"2024-11-30T19:26:52.757Z","updated_at":"2025-05-13T01:55:15.687Z","avatar_url":"https://github.com/modlfo.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Pla](/resources/pla.png?raw=true \"Pla\")\n\nPla is a simple library and ppx syntax extension to create composable templates based on verbatim strings.\n\n[Project page](https://modlfo.github.io/pla/)\n\n[Full API](https://modlfo.github.io/pla/pla_ppx.docdir/Pla.html)\n\n[![Build Status](https://travis-ci.org/modlfo/pla.svg?branch=master)](https://travis-ci.org/modlfo/pla)\n\n## Basic usage\n\nTo create templates from basic types you can use the following functions:\n\n```ocaml\nlet str_template   : Pla.t = Pla.string \"text\" ;;\nlet int_template   : Pla.t = Pla.int 1 ;;\nlet float_template : Pla.t = Pla.float 1.0 ;;\n```\nTemplates from verbatim strings are created using the markers `[%pla{|` to start the string and `|}]` to close it. For example:\n\n```ocaml\nlet code_template : Pla.t = [%pla{| you can put anything \"here\" !!! |}] ;;\n```\nTo compose templates you can use the special markers `\u003c#` and `#\u003e`. For example:\n```ocaml\nlet name  : Pla.t = Pla.string \"Bob\" ;;\nlet value : Pla.t = Pla.int 10 ;;\nlet text  : Pla.t = [%pla{|The name is \u003c#name#\u003e and the value is \u003c#value#\u003e|}] ;;\n```\nWhen printing the template the markers `\u003c#name#\u003e` and `\u003c#value#\u003e` will be replaced by the contents of the templates `name` and `value` found in the scope.\n\n```ocaml\n# Pla.print text ;;\n- : bytes = \"The name is Bob and the value is 10\"\n```\nAlternatively you can write a template to a file as follows\n```ocaml\n# Pla.write \"file.txt\" text ;;\n- : unit = ()\n```\n\nThere exist special markers to print values other than `Pla.t`. To print integers, strings and floats (without needing to convert them to template first) use the following markers:\n\n- `\u003c#...#s\u003e` for string values\n- `\u003c#...#i\u003e` for int values\n- `\u003c#...#f\u003e` for float values\n\nFor example:\n\n```ocaml\nlet name      : string = \"Bob\" ;;\nlet int_val   : int    = 10 ;;\nlet float_val : float  = 10.0 ;;\nlet text      : Pla.t  = [%pla{| String \u003c#name#s\u003e, int value \u003c#int_val#i\u003e, float value \u003c#float_val#f\u003e|}] ;;\n```\n\nThis will produce the following string:\n```ocaml\n# Pla.print text ;;\n- : bytes = \"String Bob, int value 10, float value 10.0\"\n```\n\nThe markers are type-checked so if the types do not match you will get a compile error.\n\nThere are two special markers more:\n\n- `\u003c#...#+\u003e` this will indent all the contents of the template\n- `\u003c#\u003e` this will explicitly insert a new line\n\nFor example:\n```ocaml\nlet lines : Pla.t = [%pla{|Line 1\u003c#\u003eLine 2|}] ;;\nlet text  : Pla.t = [%pla{|The lines are:\u003c#lines#+\u003e|}] ;;\n```\n\nwill produce the text:\n```\nThe lines are:\n   Line 1\n   Line 2\n```\n\nThe Pla library provides a few useful functions\n- `join` : appends a list of templates.\n- `map_join` : applies the function `f` to each element and appends all the templates.\n- `map_sep` : applies the function `f` to each element and appends all the templates separated by the template `sep`.\n\nPla also provides a few predefined templates:\n- `unit` : empty template\n- `newline` : to print a new lines\n- `comma` : to print a comma\n- `semi` : to print a semicolon\n\nNote: You can find more information in the documentation.\n\nOne example of using the previous functions is the following:\n\n```ocaml\nlet data = [1; 2; 3] ;;\nlet text = Pla.map_sep Pla.comma Pla.int data ;; (* produces: 1,2,3 *)\n```\n\n#### Adding Pla to your Project\n\nIn order to create templates with `[%pla{|...|}]` you need to preprocess the files with the ppx `pla.ppx` and link with the `pla` library.\n\nWhen using dune you have to add the `libraries` and `preprocess` fields as shown below.\n\n```\n(executables\n   (names main)\n   (libraries pla)\n   (preprocess (pps pla.ppx))\n)\n```\n\n\nWhen using ocamlbuild this can be done by adding the following lines to the `_tags` file:\n```\n\u003c*.ml\u003e: package(pla.ppx)\n\u003c*.byte\u003e: package(pla)\n\u003c*.native\u003e: package(pla)\n```\n\n#### Features and Limitations\n\nPla does not provide advanced pretty-printing features like the ones available in libraries like Format or others. On the other hand, it produces fast code whose performance is near to manually written code. Internally, every template is a function that writes text to a `Buffer.t`.\n\n## Installing\n\n```\n$ opam install pla\n```\n\n### Requirements\n\n#### Compiler\n\n- OCaml      \u003e= 4.02\n\n#### Libraries\n\n- ocaml-compiler-libs\n- ppxlib\n- dune\n\n## Syntax for Pla Templates\n\nTemplates are delimited by `[%pla{|` and `|}]`.\n\n```ocaml\nlet _ = [%pla{|\nThis is a verbatim string.\nYou can put whatever text you want.\nThe compiler will create the corresponding string.\nYou don't need to escape the \"quotes\".\n|}];;\n```\n\nWhen using OCaml 4.12 or higher, you can write the templates a follows:\n\n```\nlet x = {%pla|...|}        === let x = [%pla{|...|}]\n```\n\n#### Markers\n\nThe following markers in a `[%pla{|...|}]` template are replaced:\n\n- `\u003c#\u003e`       - inserts a new line\n- `\u003c#name#\u003e`  - inserts the contents of a `Pla.t` value\n- `\u003c#name#s\u003e` - inserts the contents of a `string` value\n- `\u003c#name#i\u003e` - inserts the contents of a `int` value\n- `\u003c#name#f\u003e` - inserts the contents of a `float` value\n- `\u003c#name#+\u003e` - creates an indented block and print the contents of a `Pla.t` value\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodlfo%2Fpla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodlfo%2Fpla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodlfo%2Fpla/lists"}