{"id":13879695,"url":"https://github.com/evilmartians/liquor","last_synced_at":"2025-04-12T00:56:09.289Z","repository":{"id":1023219,"uuid":"851135","full_name":"evilmartians/liquor","owner":"evilmartians","description":"Liquor is a safe sandboxing compiling template language for Ruby","archived":false,"fork":false,"pushed_at":"2014-12-12T14:45:08.000Z","size":1010,"stargazers_count":60,"open_issues_count":2,"forks_count":6,"subscribers_count":52,"default_branch":"master","last_synced_at":"2025-04-12T00:56:04.374Z","etag":null,"topics":["liquor","ruby","template","template-engine"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evilmartians.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-08-20T13:05:42.000Z","updated_at":"2024-12-10T03:20:58.000Z","dependencies_parsed_at":"2022-08-16T11:50:28.990Z","dependency_job_id":null,"html_url":"https://github.com/evilmartians/liquor","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmartians%2Fliquor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmartians%2Fliquor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmartians%2Fliquor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmartians%2Fliquor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evilmartians","download_url":"https://codeload.github.com/evilmartians/liquor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501879,"owners_count":21114683,"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":["liquor","ruby","template","template-engine"],"created_at":"2024-08-06T08:02:29.340Z","updated_at":"2025-04-12T00:56:09.265Z","avatar_url":"https://github.com/evilmartians.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Liquor\n\nLiquor is a safe and extensible templating language that compiles to Ruby.\nIt can be thought of as a replacement of [Liquid](https://github.com/Shopify/liquid),\nthough it does not provide a migration path.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'liquor'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install liquor\n\n## Usage\n\nThe language is described in [the specification](http://evilmartians.github.io/liquor/language-spec.html).\n\n### Compiling templates\n\nThe Liquor templates are rendered in two stages. First, you need to compile them using `Liquor::Manager`. Assuming `templates` is a hash mapping template names to contents and predefined variables, the following code demonstrates the usage of `Liquor::Manager`:\n\n``` ruby\nmanager = Liquor::Manager.new\n\ntemplates.each do |name, (body, predefined)|\n  if manager.partial? name\n    manager.register_partial name, body\n  else\n    manager.register_template name, body, predefined\n  end\nend\n\nunless manager.compile\n  manager.errors.each do |error|\n    source, * = templates[error.location[:file]]\n    puts error.decorate(source)\n  end\nend\n```\n\nThe `error.decorate` call will extract the corresponding line from the source and highlight the character range that caused the error.\n\n### Rendering templates\n\nThe `context` is a hash that is shared between the layout and the inner template. The `layout_environment` and `inner_environment` contain the list of variables initially provided to corresponding template; it must match the value of `predefined` of the template at compilation time.\n\n``` ruby\ncontext ||= {}\n\n# Production-mode code\ndiagnostics = Liquor::Runtime.capture_diagnostics do\n  inner = manager.render(template_name, inner_environment, context)\n  manager.render(layout_name, layout_environment, context.merge(_inner_template: inner))\nend\n\n# Development-mode code\nLiquor::Runtime.with_fatal_deprecations do\n  # idem\nend\n```\n\nThe difference between development-mode and production-mode code is that in development mode, all runtime errors are raised as `Liquor::Diagnostic` exceptions, and in production mode, they are returned from `Liquor::Runtime.capture_diagnostics` instead.\n\nThe code to perform decoration of the errors is the same as for compile-time errors.\n\nAdditionally, both development-mode and production-mode code can raise `Liquor::HostError` at render time, reserved for uncaught Ruby exceptions inside Liquor code.\n\n### Extending Liquor\n\nLiquor _functions_ are similar to Ruby functions. They should not have any side effects. To learn how to define your own Liquor functions, see [lib/stdlib/builtin_functions.rb](lib/stdlib/builtin_functions.rb).\n\nLiquor _tags_ provide means for inserting arbitrary Ruby code in the compiled output. They can do almost anything, and can have side effects. To learn how to define your own Liquor tags, see [lib/stdlib/builtin_tags.rb](lib/stdlib/builtin_tags.rb).\n\nBoth functions and tags are organized in _libraries_. A Liquor library looks like this:\n\n``` ruby\nmodule LiquorFoo\n  include Liquor::Library\n\n  function # ...\n\n  tag # ...\nend\n```\n\nThe libraries should be provided to the `Liquor::Manager` constructor, e.g. `Liquor::Manager.new(import: [LiquorFoo])`.\n\n### Passing Ruby objects to Liquor code\n\nLiquor represents primitive Liquor objects (null, booleans, integers, strings and tuples) using the corresponding primitive Ruby objects, so they can be passed as-is. Liquor does not extend core Ruby classes.\n\nAll other objects must include `Liquor::External` in order to be accessible from Liquor. They need to call `export` on module level to explicitly mark functions as accessible to Liquor. The functions always receive two arguments: the unnamed argument and the hash of keyword arguments, e.g.:\n\n``` ruby\nclass FooExternal\n  include Liquor::External\n\n  def meth(arg, kwargs)\n    # ...\n  end\n  export :meth\n```\n\nAdditionally, external methods can be deprecated using `deprecate :meth, date: '2014-11-11', message: 'meth is deprecated, use meth1 instead'`. The _date_ (i.e. the intended date of final removal) and _message_ will appear in the message of the emitted `Liquor::Diagnostic`. The diagnostic will only be emitted when the method is actually called.\n\n### Library integrations\n\nLiquor contains code to integrate with some popular libraries\n\n#### ActiveRecord\n\nLiquor contains built-in support for passing ActiveRecord scopes and model instances as externals. To use it, `require 'liquor/dropable'`, then `include Liquor::Dropable` in the model, and then simply pass the scope or model instance to the template.\n\n#### Rails\n\nLiquor contains a Rails renderer for Liquor templates that supports layouts. To use it `require 'liquor/extensions/rails', then use the following code in your actions:\n\n``` ruby\nrender liquor: {\n         manager:     manager,\n         template:    template_name,\n         layout:      layout_name,\n         environment: environment,\n       }\n```\n\nSee the section \"Renering templates\" for the meaning of the renderer arguments.\n\n#### Kaminari\n\nTo use Kaminari integration, `require 'liquor/extensions/kaminari'`. This will monkey-patch `Kaminari::PaginatableArray` and allow to pass any object paginated by Kaminari to Liquor templates.\n\n#### Tire\n\nTo use Tire integration, `require 'liquor/extensions/tire'`. This will monkey-patch `Tire::Results::Collection` and `Tire::Search::Search` and allow to pass any object generated by Tire to Liquor templates.\n\n#### ThinkingSphinx\n\nTo use ThinkingSphinx integration, `require 'liquor/extensions/thinking_sphinx'`. This will monkey-patch `ThinkingSphinx::Search` and allow to pass any object generated by ThinkingSphinx to Liquor templates.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\u003ca href=\"https://evilmartians.com/\"\u003e\n\u003cimg src=\"https://evilmartians.com/badges/sponsored-by-evil-martians.svg\" alt=\"Sponsored by Evil Martians\" width=\"236\" height=\"54\"\u003e\u003c/a\u003e\n\n## License\n\nLiquor is distributed under the terms of [MIT license](MIT-LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilmartians%2Fliquor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevilmartians%2Fliquor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilmartians%2Fliquor/lists"}