{"id":19854029,"url":"https://github.com/wall-brew-co/common-beer-format","last_synced_at":"2025-05-02T01:30:27.775Z","repository":{"id":37010591,"uuid":"247962161","full_name":"Wall-Brew-Co/common-beer-format","owner":"Wall-Brew-Co","description":"A cross-format implementation of the BeerXML standard","archived":false,"fork":false,"pushed_at":"2025-04-30T22:48:40.000Z","size":2819,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-30T23:30:46.517Z","etag":null,"topics":["beer","beer-format","beerxml","clojure","clojure-library","clojurescript","clojurescript-library","cross-format","edn","json","xml"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wall-Brew-Co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-03-17T12:18:25.000Z","updated_at":"2025-04-22T01:24:13.000Z","dependencies_parsed_at":"2024-02-19T23:33:14.394Z","dependency_job_id":"a43a9a64-b9c1-4c2b-aab6-2be631709af7","html_url":"https://github.com/Wall-Brew-Co/common-beer-format","commit_stats":{"total_commits":168,"total_committers":5,"mean_commits":33.6,"dds":0.4821428571428571,"last_synced_commit":"dde804dad26f9e00cfe01169de44da792277429e"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wall-Brew-Co%2Fcommon-beer-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wall-Brew-Co%2Fcommon-beer-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wall-Brew-Co%2Fcommon-beer-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wall-Brew-Co%2Fcommon-beer-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wall-Brew-Co","download_url":"https://codeload.github.com/Wall-Brew-Co/common-beer-format/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251969237,"owners_count":21673180,"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":["beer","beer-format","beerxml","clojure","clojure-library","clojurescript","clojurescript-library","cross-format","edn","json","xml"],"created_at":"2024-11-12T14:08:22.385Z","updated_at":"2025-05-02T01:30:27.453Z","avatar_url":"https://github.com/Wall-Brew-Co.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# common-beer-format\n\n[![Clojars Project](https://img.shields.io/clojars/v/com.wallbrew/common-beer-format.svg)](https://clojars.org/com.wallbrew/common-beer-format)\n[![cljdoc badge](https://cljdoc.org/badge/com.wallbrew/common-beer-format)](https://cljdoc.org/d/com.wallbrew/common-beer-format/CURRENT)\n[![GitHub](https://img.shields.io/github/license/Wall-Brew-Co/common-beer-format)](https://github.com/Wall-Brew-Co/common-beer-format/blob/master/LICENSE)\n[![Twitter Follow](https://img.shields.io/twitter/follow/WallBrew?style=social)](https://twitter.com/WallBrew)\n\nA Clojure(Script) implementation of the [BeerXML 1.0 schema](http://www.beerxml.com/) with cross-format support using Metosin's [spec-tools.](https://github.com/metosin/spec-tools)\nThe library endeavors to support the data specification as a [clojure spec](https://clojure.org/about/spec) and includes all optional fields in the core BeerXML spec.\n\nThis repository follows the guidelines and standards of the [Wall Brew Open Source Policy.](https://github.com/Wall-Brew-Co/open-source \"Our open source guidelines\")\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Domain Experience](#domain-experience)\n- [Installation](#installation)\n- [Documentation](#documentation)\n- [Usage](#usage)\n  - [Core Data Functions](#core-data-functions)\n- [Additional Notes](#additional-notes)\n  - [Wrappers](#wrappers)\n  - [Pre-Packaged Data](#pre-packaged-data)\n  - [Alternative Representations](#alternative-representations)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Domain Experience\n\nThis documentation and library assumes a moderately advanced level of familiarity with homebrewing- specifically the brewing of beer.\nIf you are unfamiliar with the brewing process, we highly recommend setting this documentation aside and gathering the essential experience and knowledge first.\nThe following resources are great places to begin:\n\n- *The Complete Joy of Home Brewing* - Charlie Papazian\n- *How to Brew* - John J. Palmer\n- [The American Homebrewers Association](https://www.homebrewersassociation.org/)\n- A friend, relative, or neighbor with homebrewing experience\n- A local brewery or local homebrewing supply store\n\n## Installation\n\nA deployed copy of the most recent version of [common-beer-format can be found on clojars.](https://clojars.org/com.wallbrew/common-beer-format)\nTo use it, add the following as a dependency in your project.clj file:\n\n[![Clojars Project](https://clojars.org/com.wallbrew/common-beer-format/latest-version.svg)](https://clojars.org/com.wallbrew/common-beer-format)\n\nThe next time you build your application, [Leiningen](https://leiningen.org/) or [deps.edn](https://clojure.org/guides/deps_and_cli) should pull it automatically.\nAlternatively, you may clone or fork the repository to work with it directly.\n\n## Documentation\n\ncommon-beer-format's public documentation is available on [cljdoc.](https://cljdoc.org/d/com.wallbrew/common-beer-format/CURRENT)\nPlease note that cljdoc does not currently include clojure specs in auto-generated namespace documentation.\nDocumentation of the specs contained by this library may be found in the `Specs` article.\nThe original markdown copies of this documentation are located in the `doc` folder of this repository.\n\n## Usage\n\nOnce the library has been added as a dependency to your project, you can begin utilizing the specs.\n\nTo see how the application works, try opening a REPL.\n\n```clj\n(:require [clojure.data.xml :as xml]\n          [clj-xml.core :as clj-xml]\n          [common-beer-format.core :as cbf]\n          [common-beer-format.fermentables :as cbf-fermentables])\n\n(def fermentables-file\n  (-\u003e \"resources/xml/fermentables.xml\"\n      slurp\n      xml/parse-str\n      clj-xml/xml-\u003eedn))\n\n(cbf/coerce fermentables-file ::cbf-fermentables/fermentables-wrapper)\n```\n\nOnce the file is read and parsed, the code above will return something like this:\n\n```clj\n  {:fermentables\n   [{:fermentable\n     {:amount           2.27\n      :yield            78.0\n      :supplier         \"Fussybrewer Malting\"\n      :color            3.0\n      :name             \"Pale Malt (2 row) UK\"\n      :moisture         4.0\n      :type             \"Grain\"\n      :notes            \"All purpose base malt for English styles\"\n      :protein          10.2\n      :origin           \"United Kingdom\"\n      :coarse-fine-diff 1.5\n      :version          1\n      :max-in-batch     100.0\n      :diastatic-power  45.0}}\n    {:fermentable\n     {:amount           0.91\n      :yield            70.0\n      :supplier         \"Fussybrewer Malting\"\n      :color            2.0\n      :name             \"Barley, Flaked\"\n      :moisture         9.0\n      :type             \"Grain\"\n      :notes            \"Adds body to porters and stouts, must be mashed\"\n      :protein          13.2\n      :origin           \"United Kingdom\"\n      :coarse-fine-diff 1.5\n      :version          1\n      :max-in-batch     20.0\n      :recommend-mash   true\n      :diastatic-power  0.0}}\n    {:fermentable\n     {:amount           0.45\n      :yield            78.0\n      :supplier         \"Fussybrewer Malting\"\n      :color            500.0\n      :name             \"Black Barley\"\n      :moisture         5.0\n      :type             \"Grain\"\n      :notes            \"Unmalted roasted barley for stouts, porters\"\n      :coarse-fine-diff 1.5\n      :diastatic-power  0.0\n      :protein          13.2\n      :max-in-batch     10.0}}]}\n```\n\nThis library takes data structured to the [BeerXML](http://www.beerxml.com/beerxml.htm) specification and provides a layer of conformance and coercion.\n\nSpecs for the following data types have been provided, as well as several wrappers for container objects:\n\n- [Equipment](/src/common_beer_format/equipment.cljc)\n- [Fermentables](/src/common_beer_format/fermentables.cljc)\n- [Hops](/src/common_beer_format/hops.cljc)\n- [Mash](/src/common_beer_format/mash.cljc)\n- [Miscs](/src/common_beer_format/miscs.cljc)\n- [Recipes](/src/common_beer_format/recipes.cljc)\n- [Styles](/src/common_beer_format/styles.cljc)\n- [Waters](/src/common_beer_format/waters.cljc)\n- [Yeasts](/src/common_beer_format/yeasts.cljc)\n\n### Core Data Functions\n\nIn the core namespace, several utility functions have been provided to allow users of common-beer-format to inherit the utilities in `spec-tools`.\nThat users may use any function from `spec-tools` or `clojure.spec`, with the specs in this library.\n\nSurfaced functions include:\n\n- `conform`\n- `coerce`\n- `explain`\n- `explain-data`\n- `spec-description`\n\n## Additional Notes\n\n### Wrappers\n\nSince BeerXML was obviously built to XML standards, this data model contains more container objects than either JSON or EDN traditionally.\nTo cleanly interop with Clojure Spec, this required the construction of spec wrappers for forms like the following:\n\n```clj\n  {:fermentables\n   [{:fermentable ...}\n    {:fermentable ...}]}\n\n;; as well as\n\n{:fermentable\n  {:amount           2.27\n   :yield            78.0\n   :supplier         \"Fussybrewer Malting\"\n   :color            3.0\n   :name             \"Pale Malt (2 row) UK\"\n   :moisture         4.0\n   :type             \"Grain\"\n   :notes            \"All purpose base malt for English styles\"\n   :protein          10.2\n   :origin           \"United Kingdom\"\n   :coarse-fine-diff 1.5\n   :version          1\n   :max-in-batch     100.0\n   :diastatic-power  45.0}}\n```\n\nTherefore, specs named like `::fermentable` and `::fermentables` are used to describe the innermost values- meaning a key-value pair of the data describing a fermentable ingredient or a list of fermentable records.\nTo coerce and conform the data containing those elements, one would use `::fermentable-wrapper` and `::fermentables-wrapper`.\nThat allows the clean interop between the internal data structure of `clojure.data.xml`, which defines the data samples above, and the utilities provided by `spec-tools`.\n\n### Pre-Packaged Data\n\ncommon-beer-format formerly came pre-packaged with many of the most common brewing ingredients used.\nWhile this was convenient, it severely bloated this library and its published version.\nThis information is still available; however, it must now be loaded as a separate dependency as of `common-beer-format v2.0.0`.\nYou can find that data in the [common-beer-data](https://github.com/Wall-Brew-Co/common-beer-data) repository.\n\nIf we've missed an ingredient you'd like to see in common-beer-data, you can fork that repository and open a pull request or [suggest it here.](https://github.com/Wall-Brew-Co/common-beer-data/issues/new?template=data_request.md)\n\n### Alternative Representations\n\nIn addition to surfacing clojure.spec definitions for the BeerXML schema, this library also provides exported type/schema information in the following formats:\n\n- [JSON Schema](https://json-schema.org/specification)\n\nThese files are generated from the clojure.spec definitions and are available in the `exports` directory of this repository.\n\n## License\n\nCopyright © [Wall Brew Co](https://wallbrew.com/)\n\nThis software is provided for free, public use as outlined in the [MIT License](https://github.com/Wall-Brew-Co/common-beer-format/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwall-brew-co%2Fcommon-beer-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwall-brew-co%2Fcommon-beer-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwall-brew-co%2Fcommon-beer-format/lists"}