[ { "path": ".gitignore", "content": "pkg\n.bundle\ncoverage\nGemfile.lock\n*~\n.yardoc\ndoc\nFORMATS.html\nscratch\n.ruby-version\n.ruby-gemset\nJarfile.lock\n" }, { "path": ".rubocop.yml", "content": "AllCops:\n Exclude:\n - 'pkg/**/*'\n - 'vendor/**/*'\n - 'bench/**/*'\n\nLint/AmbiguousRegexpLiteral:\n Enabled: false\n\nLint/AmbiguousOperator:\n Enabled: false\n\nLint/AssignmentInCondition:\n Enabled: false\n\nMetrics/AbcSize:\n Enabled: false\n\nMetrics/ClassLength:\n Enabled: false\n\nMetrics/CyclomaticComplexity:\n Enabled: false\n\n# FIXME: lower by fixing the biggest offenders\nMetrics/LineLength:\n Max: 184\n\nMetrics/MethodLength:\n Enabled: false\n\nMetrics/PerceivedComplexity:\n Enabled: false\n\n# def_delegators’ first symbol is the target, the rest are calls\nStyle/AlignParameters:\n Enabled: false\n\n# FIXME: should this be normalised to `EnforcedStyle: semantic`?\nStyle/BlockDelimiters:\n Enabled: false\n\n# including parametrised modules looks much better without this alignment\nStyle/ClosingParenthesisIndentation:\n Enabled: false\n\nStyle/ConstantName:\n Exclude:\n - yaks/lib/yaks/breaking_changes.rb\n\nStyle/Documentation:\n Enabled: false\n\nStyle/EmptyLineBetweenDefs:\n AllowAdjacentOneLineDefs: true\n\nStyle/FileName:\n Exclude:\n - yaks-html/lib/yaks-html.rb\n - yaks-sinatra/lib/yaks-sinatra.rb\n - yaks-transit/lib/yaks-transit.rb\n\n# including parametrised modules looks much better without this indentation\nStyle/FirstParameterIndentation:\n Enabled: false\n\nStyle/FormatString:\n EnforcedStyle: percent\n\nStyle/GlobalVars:\n Exclude:\n - bench/bench.rb\n - bench/bench_1000.rb\n\nStyle/HashSyntax:\n Exclude:\n - Rakefile\n\n# some arrays need deeper indenting for readability\nStyle/IndentArray:\n Enabled: false\n\nStyle/IndentationWidth:\n Exclude:\n - yaks/lib/yaks/breaking_changes.rb\n\n# the codebase uses -> consistently\nStyle/Lambda:\n Enabled: false\n\n# FIXME: figure out why fixing this blows tests up\nStyle/MethodCallParentheses:\n Enabled: false\n\nStyle/ModuleFunction:\n Exclude:\n - yaks/lib/yaks/util.rb\n\nStyle/MultilineBlockChain:\n Enabled: false\n\nStyle/PercentLiteralDelimiters:\n Exclude:\n - yaks/lib/yaks/breaking_changes.rb\n - yaks/spec/unit/yaks/config_spec.rb\n PreferredDelimiters:\n '%i': '[]'\n '%w': '[]'\n '%W': '[]'\n\nStyle/PerlBackrefs:\n Enabled: false\n\nStyle/Semicolon:\n AllowAsExpressionSeparator: true\n\nStyle/SignalException:\n EnforcedStyle: only_raise\n\nStyle/SpaceBeforeSemicolon:\n Enabled: false\n\n# FIXME: this should be enforced to either space or no_space\nStyle/SpaceBeforeBlockBraces:\n Enabled: false\n\n# FIXME: this should be enforced to either space or no_space\nStyle/SpaceInsideBlockBraces:\n Enabled: false\n\n# FIXME: make a call whether to fix this one or not\nStyle/SpaceInsideBrackets:\n Enabled: false\n\nStyle/SpaceInsideHashLiteralBraces:\n EnforcedStyle: no_space\n\nStyle/SpaceInsideStringInterpolation:\n Enabled: false\n\n# FIXME: enforce either single_quotes (fewer fixes) or double_quotes\nStyle/StringLiterals:\n Enabled: false\n\nStyle/UnneededPercentQ:\n Exclude:\n - yaks/lib/yaks/breaking_changes.rb\n\nStyle/TrailingComma:\n Enabled: false\n\n# Allow redundant braces in foo.bar({\"qux\" => \"quz\"}), when writing\n# e.g. JSON tests this can be more explicit and clear\nStyle/BracesAroundHashParameters:\n Exclude:\n - yaks/spec/**/*\n\nStyle/SpaceInsideStringInterpolation:\n Enabled: false\n\nStyle/LambdaCall:\n Enabled: false\n" }, { "path": ".travis.yml", "content": "language: ruby\n\nrvm:\n - 2.2\n - 2.3.4\n - 2.4.2\n - jruby\n - jruby-head\n - ruby-head\n\ncache: bundler\n\nsudo: false\n\nscript: bundle exec rake $TASK\n\nenv:\n - TASK=yaks:rspec\n - TASK=yaks-html:rspec\n - TASK=yaks-sinatra:rspec\n\nmatrix:\n allow_failures:\n - rvm: ruby-head\n - rvm: jruby-head\n - rvm: rbx\n - env: TASK=mutant\n fast_finish: true\n include:\n - rvm: rbx\n env: TASK=\"yaks:rspec --trace\"\n - rvm: rbx\n env: TASK=\"yaks-html:rspec --trace\"\n - rvm: rbx\n env: TASK=\"yaks-sinatra:rspec --trace\"\n - rvm: 2.2\n env: TASK=ataru\n - rvm: 2.2\n env: TASK=mutant\n" }, { "path": "ADDING_FORMATS.md", "content": "# Adding Extra Output Formats to Yaks\n\nIndividual output formats are each handled by a dedicated `Yaks::Serializer` class. These take a `Yaks::Resource` as input, and turn it into the requested output format.\n\nA `Yaks::Resource` is created by \"mapping\" domain models by a `Yaks::Mapper`. In a `Yaks::Mapper` subclass a DSL is available to specify how to extract different types of information, for example attributes or links, and store them in a generalized way in a `Resource`.\n\nDifferent formats have different features. Simple formats might just represent attributes, links, and subresources, other formats have queries, forms, or RDF identifiers. If a format represents data of a different nature, then the first step is to decide on a good and straightforward syntax to specify how to derive this data. This can then be stored in a `Yaks::Resource`, and formats that support it can use it, other formats can ignore it.\n\nThis is already the case, JSON-API ignores links for example.\n\nSo adding an output format is generally straightforward, as long as the information that the output format supports is already available in `Yaks::Resource`. In that case adding a `Yaks::Serializer::YourFormat` is all that is needed.\n\nIf the format has features that are not yet available then syntax needs to be added for those features. The guiding idea there is to try and find more than one format with the given feature, to make sure the intermediate abstraction is general and not tied to the specifics and vocabulary of a single format.\n" }, { "path": "CHANGELOG.md", "content": "### master\n[all changes](http://github.com/plexus/yaks/compare/v0.13.0...master)\n\n### v0.13.0 / 2017-11-13\n[all changes](http://github.com/plexus/yaks/compare/v0.12.0...v0.13.0)\n\n* Maintenance release to upgrade dependencies\n\n### v0.12.0 / 2016-03-28\n[all changes](http://github.com/plexus/yaks/compare/v0.11.0...v0.12.0)\n\n* `attribute` can now take an `if` parameter, just like links and forms\n\n### v0.11.0 / 2015-07-09\n[all changes](http://github.com/plexus/yaks/compare/v0.10.0...v0.11.0)\n\n* Updated JSON-API to match 1.0 format. ([Yohan Robert](https://github.com/groyoh) and [Janko Marohnić](https://github.com/janko-m))\n* Added Yaks::Behaviour::OptionalIncludes, to support JSON-API style\n optional associations ([Janko Marohnić](https://github.com/janko-m))\n* Renamed Sinatra::Yaks to Yaks::Sinatra ([Matt Patterson](https://github.com/fidothe))\n* Correctly handle 'charset' in Yaks::Sinatra ([Matt Patterson](https://github.com/fidothe))\n* Fix rendering of checkboxes in yaks-html\n* Add integration for testing through RSpec/Capybara/Rack::Test\n\n### v0.10.0 / 2015-05-19\n[all changes](http://github.com/plexus/yaks/compare/v0.9.0...v0.10.0)\n\n* Updated JSON-API Reader to handle collections\n\n* Further changes to bring JSONAPI formatting more in line with 1.0\n format\n\n - Changed `linked` to `included`\n - Change format of `links` to include 'linkages'\n - `included` no longer contains duplicates\n - Render top level collection links\n - Don't include \"rel\" in links output\n\n* yaks-html: Make nested resources expand/collapse, various small\n improvements\n\n* yaks-html: render \"rel\" attributes, making the HTML output more suitable\n for use in integration tests\n\n* In mapper/form declarations: make methods that take a lambda to also\n accept a block\n\n* Instead of representing form fieldset legends as form fields, give\n them their own class\n\n* Introduce `Yaks::Form#fields_flat`, an enumerator to traverse all\n input fields in a form linearly, e.g. for validation. Will skip over\n legend elements\n\n* Introduce `Yaks::Form#map_fields`, a way to map over fields and fieldsets\n recursively, yielding a new nested object\n\n* Bug fix: `json_serializer` configuration method not working as intended\n\n* Improved mapper lookup to deal with model inside namespace\n\n* Introduce `mapper_for`, a configuration option for setting up one-off\n mapper derivation rules\n\n* Reify Form::Legend, making it easier to handle form objects with field sets\n\n* Improve test coverage. We are now at 97.30% mutation coverage\n\n* Improve documentation. Code examples in the README are now verified with\n Ataru\n\n* Make code warning-free\n\n\n### v0.9.0 / 2015-03-17\n\nMake dynamic form fields respect the order in which they were declared\nin the form relative to other form fields.\n\nSome changes to bring JSONAPI formatting more in line with 1.0 format\n\n - Top level key must be named 'data' rather than the resource type\n - The resource name myst be included in a 'type' attribute\n\nStarted a Reader for JSONAPI, which can build a resource from JSONAPI input.\n\nAdd if: options to Form::Field, Form::Fieldset, and Form::Field\noption, just as on links, associations, and forms.\n\nAllow form field details to be expressed in a block, and allow\nConfigurable \"setters\" to take a block instead of a direct argument.\n\n``` ruby\ntext :first_name,\n label: 'views.checkout.first_name',\n required: true,\n value: ->{ customer_attribute(:first_name) }\n```\n\nbecomes\n\n```\ntext :first_name do\n required true\n label 'views.checkout.first_name'\n value { customer_attribute(:first_name) }\nend\n```\n\nThis makes the DSL more consistent, since e.g. `label` could already\nbe set in this way, but not `value` or `required`.\n\nPrevent `:if` on a form field to be rendered as a form element\nattribute.\n\n### v0.8.3 / 2015-03-09\n\nThe default policy for resolving mappers will now look up superclass\nnames of the object being serialized, so you can define a single\nmapper to handle a class hierarchy.\n\n### v0.8.2 / 2015-03-02\n\nVarious improvements to the HTML formatter\n\n- use the form name as a title if there's no title\n- remove the link styling on rels to indicate they are purely\n identifiers\n- link IANA registered rels (indicated by using a symbol) to the IANA\n list\n- style the hierarchy in a cleaner way by using a gray left border\n rather than complete boxes\n- Add a header that shows the current request method/path\n- Add a footer that shows the yaks version\n- show the name/value of hidden form fields\n- get rid of the all the border-radius, try a new color scheme\n\n### v0.8.1 / 2015-02-20\n\nAdd `disabled` as a possible attribute of a select option, so you can\nrender form select controls with disabled options.\n\n### v0.8.0 / 2015-02-18\n\nAllow to use procs for dynamic values in \"option\" form elements (as\nused inside a \"select\"). This makes the form API more consistent.\n\nAdd an `:if` option to links, to only render them upon a certain\ncondition.\n\nAdd an `:if` option to forms, and a corresponding `condition` method\n(it's tricky to have a method called `if`), to only render them upon a\ncertain condition.\n\nAdd an `:if` option to associtions, to only render them upon a certain\ncondition.\n\n### 0.8.0.beta2 / 2015-01-14\n\nIn form select fields, allow the attributes of options to be generated\ndynamically by passing procs, in line with other form related\nattributes\n\n### 0.8.0.beta1 / 2015-01-09\n\nImproved form support, HTML form rendering, CJ support.\n\n### 0.8.0.alpha / 2014-12-17\n\nImproved Collection+JSON support, dynamically generated form fields.\n\n#### Collection+JSON\n\nCarles Jove i Buxeda has done some great work to improve support for Collection+JSON, GET forms are now rendered as CJ queries.\n\n#### Dynamic Form Fields\n\nA new introduction are \"dynamic\" form fields. Up to now it was hard to generate forms based on the object being serialized. Now it's possible to add dynamic sections to a Form definition. These will be evaluated at map-time, they receive the object being mapped, and inside the syntax for defining form fields can be used.\n\n```\nform :checkout do\n text :name\n text :lastname\n\n dynamic do |object|\n object.shipping_options.each do |shipping|\n radio shipping.type_name, title: shipping.description\n end\n end\nend\n```\n\n#### Fieldset and Legend\n\nSupport for the fieldset element type has been added, which works as you would expect\n\n```\nform :foo do\n fieldset do\n legend \"Hello\"\n text :field_1\n end\nend\n```\n\n#### Remove links\n\nA link defined in a mapper can be removed in a derived mapper. This is useful when you have a base mapper defining for example 'self' or 'profile' links, but for some derived mappers you don't want these in the output.\n\n```\nclass BaseMapper\n link :self, \"/api/{mapper_name}/{id}\"\nend\n\nclass FooMapper < BaseMapper\n link :self, remove: true\nend\n```\n\n#### Deprecations\n\nInternally there the DSL/Config mechanisms have been made more consistent. Yaks::Config is now immutable, much like Yaks::Mapper::Config. Attributes-based classes no long have arity-based hybrid getter/setters. Instead use `with(attr: val)` to set a value.\n\nBecause of this work, two methods on Yaks::Config are considered deprecated. You will get a warning when using the old name.\n\n* json_serializer, use serializer(:json, &...)\n* namespace, use mapper_namespace\n\n#### Experimental read/write support\n\nSome work has happened on read/write support, but this is not considered stable yet.\n\n### 0.7.7 / 2014-12-02\n\nGeneral extension and improvements to form handling.\n\nAdd top level links in Collection+JSON (Carles Jove i Buxeda)\n\nThe mapper DSL method \"control\" has been renamed to \"form\". There is a\ndeprecated alias available.\n\nAdd Yaks::Resource#find_form for querying a resource for an embedded\nform by name.\n\nIntroduce yaks.map() so you can only call the mapping step without\nrunning the whole pipeline.\n\n### 0.7.6 / 2014-11-18\n\nMuch expanded form support, simplified link DSL, pretty-print objects\nto Ruby code.\n\nBreaking change: using a symbol instead of link template no longer\nworks, use a lambda.\n\n link :foo, :bar\n\nBecomes\n\n link :foo, ->{ bar }\n\nStrictly speaking the equivalent version would be `link :foo, ->{\nload_attribute(:bar) }`. Depending on if `bar` is implemented on the\nmapper or is an attribute of the object, this would simplify to `link\n:foo, ->{ bar }` or `link :foo, ->{ object.bar }` respectively.\n\nThe form control DSL has been expanded, instead of `field type:\n'text'` and similar there are now aliases, e.g. `text :name, value:\n'foo'`.\n\nAll attributes on the form control itself, and on fields, now\noptionally take a lambda (any `#to_proc`-able) for dynamic\ncontent. e.g.\n\n control :add_product do\n method 'POST'\n action ->{ '/cart/#{cart.id}/line_items' }\n hidden :product_id, value: -> { product.id }\n number :quantity, value: 0\n end\n\nAs with lambdas used for links, in case of a zero-arity lambda these\nevaluate with `self` being the mapper. If the lambda takes an argument\nthe argument will be the mapper, and the lambda is evaluated as a\nclosure.\n\nThe `href` attribute of a control has been renamed `action`, in line\nwith the attribute name in HTML. An alias is available but will output\na deprecation warning.\n\nThe Yaks::Resource#pp method has been lifted into Attributes so it's\navailable on most immutable Yaks objects. It has also been adapted to\nproduce, in most cases, output that is valid Ruby code.\n\n### 0.7.5 / 2014-11-17\n\nAdd the :replace option to link specifications. When used on a link\nwhen another link of the same rel was specified previously, then the\ncurrent link will replace the one (and any other) that was specified\nearlier.\n\nUse case:\n\n class BaseMapper < Yaks::Mapper\n link :self, '/api/{mapper_name}/{id}'\n end\n\n class CartMapper < BaseMapper\n link :self, '/api/cart', :replace => true\n end\n\n\n### 0.7.4 / 2014-11-17\n\nFix a regression in around hooks introduced in 0.7.0.\n\nImprove pretty printing (Yaks::Resource#pp)\n\n### 0.7.3 / 2014-11-11\n\nyaks-sinatra: Allow passing extra Yaks options to the helper method\n\n### 0.7.2 / 2014-11-10\n\nAllow controls to use the same expansion mechanisms that are available\nin links, i.e. URI templates, symbol referring to a method. Added\nprocs to that list as well.\n\n### 0.7.1 / 2014-11-10\n\nBugfix in CollectionMapper.\n\n### 0.7.0 / 2014-11-10\n\n#### Introduces yaks-sinatra\n\nFor easier Sinatra integration. See the respective README for more info.\n\n#### Move the rel of subresource into a resource itself\n\nBefore the subresources in a Yaks::Resource were stored in a hash,\nkeyed by rel. Now the rel is stored as a property of the resource, and\nthe subresources are a simple array. This opens the door to formats\nthat support multiple rels on a resource, and simplifies things as a\npreparatory step towards bi-directional mapping.\n\nThis change is mostly transparent to the user, but when implementing\ncustom output formats or doing testing on the resulting Resource\ninstances, you might have to update your code.\n\n#### Pass the rack env to steps and hooks\n\nYaks is a pipeline where each step implements the `call`\nmethod. Before `call` always received one argument, the previous\ntransformation step's result. Now it receives the Rack env as a second\nargument.\n\nThis also applies to before/after/around hooks, although if they are\nspecified as ruby blocks then no change is needed, the second argument\nwill be ignored.\n\n#### Handle URI instances\n\nAfter formatting for a JSON output format (e.g. HAL), but before\nactually serializing to JSON, all data needs to be of a type that has\na JSON equivalent, or needs to be handled explicitly with a conversion\n(known as \"primitivizing\"). instances of `URI` have been added to this\nlist, they will automatically be represented as JSON strings.\n\n### 0.6.2 / 2014-11-05\n\nImprovements to yaks-html: render form controls, make output prettier.\n\n### 0.6.1 / 2014-10-30\n\nMake sure Resource, NullResource, and CollectionResource have\nidentical public APIs.\n\nCreate a base Yaks::Error class, and derived classes for specific\nerror categories. This should make it easier to handle errors\noriginating in Yaks. Note that not all code makes use of these yet, so\nyou might still get a StandardError in some cases.\n\n### 0.6.0 / 2014-10-30\n\nv0.6.0 saw some big internal overhaul to make things cleaner and more\nconsistent. It also introduced some new features.\n\n#### Form controls\n\nWe already had templated links which form a limited way of generating\nparameterized requests. Form controls are more like full HTML forms,\ne.g.\n\n``` ruby\nclass UserMapper < Yaks::Mapper\n control :create do\n href \"/foo\"\n method \"POST\"\n content_type \"application/x-www-form-urlencoded\"\n\n field :first_name, label: \"First name\"\n field :last_name, label: \"Last name\"\n end\nend\n```\n\nThese are also called actions in some formats. At the moment only one\nformat renders these, a new format called HALO which is en extension\nof HAL, loosely based on an example by Mike Kelly on how HAL could be\nextended for this purpose.\n\n#### Introduce a HTML output format\n\nProvided as a separate gem, `yaks-html` allows Yaks to generate a\nversion of your API that can be browsed from any web browser. This is\nstill very rough around the edges.\n\n### 0.5.0 / 2014-09-18\n\n* Yaks now serializes (returns a string), instead of returning a data\n structure. This is a preparatory step for supporting non-JSON\n formats. To get the old behavior back, do this\n\n``` ruby\nyaks = Yaks.new do\n skip :serialize\nend\n```\n\n* The old `after` hook has been removed, instead there are now generic hooks for all steps: `before`, `after`, `around`, `skip`; `:map`, `:format`, `:primitivize`, `:serialize`.\n\n* By default Yaks uses `JSON.pretty_generate` as a JSON unparser. To use something else, for example `Oj.dump`, do this\n\n``` ruby\nyaks = Yaks.new do\n json_serializer &Oj.method(:dump)\nend\n```\n\n* Mapping a non-empty collection will try to infer the type, and hence rel of the nested items, based on the first object in the collection. This is only relevant for formats like HAL that don't have a top-level collection representation, and only matters when mapping a collection at the top level, not when mapping a collection from an association.\n\n* Collection+JSON uses a link's \"title\" attribute to output a link's \"name\", to better correspond with other formats\n\n* When registering a custom format (Yaks::Format subclass), the signature has changed\n\n``` ruby\n# 0.4.3\nFormat.register self, :collection_json, 'application/vnd.collection+json'\n\n# 0.5.0\nregister :collection_json, :json, 'application/vnd.collection+json'\n```\n\n* `yaks.call` is now the preferred interface, rather than `yaks.serialize`, although there are no plans yet to remove the alias.\n\n* The result of a call to `Yaks.new` now responds to `to_proc`, so you can treat it as a Proc/Symbol, e.g. `some_method &yaks`\n\n* Improved YARD documentation\n\n* 100% mutation coverage :trumpet: :tada:\n\n### 0.4.3 / 2014-08-25\n\n* when specifying a rel_template, instead of allowing for {src} and {dest} fields, now a single {rel} field is expected, which corresponds more with typical usage.\n\n```ruby\nYaks.new do\n rel_template 'http://my-api/docs/relationships/{rel}'\nend\n```\n\n* Yaks::Serializer has been renamed to Yaks::Format\n\n* Yaks::Mapper#{map_attributes,map_links,map_subresource} signature has changed, they now are responsible for adding themselves to a resource instance.\n\n```ruby\nclass FooMapper < Yaks::Mapper\n def map_attributes(resource)\n resource.update_attributes(:example => 'attribute')\n end\nend\n```\n\n* Conditionally turn associations into links\n\n```ruby\nclass ShowMapper < Yaks::Mapper\n has_many :events, href: '/show/{id}/events', link_if: ->{ events.count > 50 }\nend\n```\n\n* Reify `Yaks::Mapper::Attribute`\n\n* Remove `Yaks::Mapper#filter`, instead override `#attributes` or `#associations` to filter things out, for example:\n\n```ruby\nclass SongMapper\n attributes :title, :duration, :lyrics\n has_one :artist\n has_one :album\n\n def minimal?\n env['HTTP_PREFER'] =~ /minimal/\n end\n\n def attributes\n if minimal?\n super.reject {|attr| attr.name.equal? :lyrics } # These are instances of Yaks::Mapper::Attribute\n else\n super\n end\n end\n\n def associations\n return [] if minimal?\n super\n end\nend\n```\n\n* Give Attribute, Link, Association a common interface : `add_to_resource(resource, mapper, context)`\n* Add persistent update methods to `Yaks::Resource`\n\n### v0.4.2 / 2014-06-24\n\n* JSON-API: render self links as href attributes\n* HAL: render has_one returning nil as null, not as {}\n* Keep track of the mapper stack, useful for figuring out if mapping the top level response or not, or for accessing parent\n* Change Serializer.new(resource, options).serialize to Serializer.new(options).call(resource) for cosistency of \"pipeline\" interface\n* Make Yaks::CollectionMapper#collection overridable for pagination\n* Don't render links from custom link methods (link :foo, :method_that_generates_url) that return nil\n\n### v0.4.1 / 2014-06-18\n\n* Change how env is passed to yaks.serialize to match docs\n* Fix JSON-API bug (#18 reported by Nicolas Blanco)\n* Don't pluralize has_one association names in JSON-API\n\n### v0.4.0 / 2014-06-17\n\n* Introduce after {} post-processing hook\n* Streamline interfaces and variable names, especially the use of `call`\n* Improve deriving mappers automatically, even with Rails style autoloading\n* Give CollectionResource a members_rel, for HAL-like formats with no top-level collection concept\n* Switch back to using `src` and `dest` as the rel-template keys, instead of `association_name`\n* deprecate `mapper_namespace` in favor of `namespace`\n\n### v0.4.0.rc1 / 2014-06-11\n\n* Introduce Yaks.new as the main public interface\n* Fix JsonApiSerializer and make it compliant with current spec\n* Remove Hamster dependency, Yaks new uses plain old Ruby arrays and hashes\n* Remove `RelRegistry` and `ProfileRegistry` in favor of a simpler explicit syntax + policy based fallback\n* Add more policy derivation hooks, plus make `DefaultPolicy` template for rel urls configurable\n* Optionally take a Rack env hash, pass it around so mappers can inspect it\n* Honor the HTTP Accept header if it is present in the rack env\n* Add map_to_primitive configuration option\n\n### v0.3.0 / 2014-05-15\n\n* Allow partial expansion of templates, expand certain fields, leave others as URI template in the result.\n\n### v0.2.0 / 2014-03-31\n\n* links can now take a simple for a template to compute a link just like an attribute\n\n### v0.1.0 / 2014-03-07\n\n### v0.0.0 / 2013-12-09\n" }, { "path": "COOKBOOK.md", "content": "# Yaks Cookbook\n\n## Represent Date/Time objects as iso8601\n\n``` ruby\n$yaks = Yaks.new do\n map_to_primitive Date, Time, DateTime, ActiveSupport::TimeWithZone, &:iso8601\nend\n```\n\n## Make Yaks' HTML format play nice with CSRF protection\n\nMinimum version when using Rack::Protection\n\n``` ruby\n$yaks = Yaks.new do\n after :format, :add_csrf_token do |result, env|\n next result unless result.is_a?(Hexp::Node) && env.key?('rack.session')\n\n session = env['rack.session']\n session[:csrf] ||= SecureRandom.hex(32)\n token = session[:csrf]\n\n result.replace 'form' do |form|\n form.append(H[:input, type: :hidden, name: 'authenticity_token', value: token])\n end\n end\nend\n```\n\nVersion that covers all cases when using a Rack::Protection protected\nAPI mounted inside a Rails app.\n\n``` ruby\n$yaks = Yaks.new do\n after :format, :add_csrf_token do |result, env|\n next result unless result.is_a?(Hexp::Node) && env.key?('rack.session')\n\n # Rails uses '_csrf_token' as a key. Rack::Protection uses\n # :csrf, but will detect and use '_csrf_token' if :csrf is\n # absent. This works fine as long as a call to Rails is made\n # before a call to the API is made. When using the HTML\n # rendering of the API on an empty session and afterwards\n # switching to Rails though, the '_csrf_token' and :csrf\n # values will differ, causing Rack::Protection to reject\n # valid API calls. Hence this little dance to prevent that.\n\n session = env['rack.session']\n session[:csrf] ||= session['_csrf_token'] || SecureRandom.hex(32)\n session['_csrf_token'] ||= session[:csrf]\n token = session[:csrf]\n\n result.replace 'form' do |form|\n form.append(H[:input, type: :hidden, name: 'authenticity_token', value: token])\n end\n end\n```\n\n## Make Yaks' HTML format work with PUT/DELETE/etc.\n\nIf you're using `Rack::MethodOverride` or something similar, you could\ndrop this in your Yaks config to convert forms so they will work in a\nbrowser.\n\n``` ruby\nafter :format, :html_form_methods do |result, env|\n next result unless result.is_a?(Hexp::Node)\n result.replace('[method=\"PUT\"],[method=\"DELETE\"],[method=\"PATCH\"]') do |form|\n form\n .append(H[:input, type: \"hidden\", name: \"_method\", value: form[:method]])\n .attr(\"method\", \"POST\")\n end\nend\n```\n\n## Implement Pagination\n\nIn a hypermedia API the typical way to provide pagination is by adding\n\"previous\" and \"next\" links on a collection. You can do this by\nimplementing your own CollectionMapper\n\n```\nmodule Mappers\n class CollectionMapper < Yaks::CollectionMapper\n PAGE_SIZE = 50\n\n link :previous, -> { previous_link }\n link :next, -> { next_link }\n\n def params\n Rack::Request.new(env).params\n end\n\n def offset\n params.fetch('offset') { 0 }.to_i\n end\n\n alias full_collection collection\n\n def collection\n # You can implement more efficient page slicing based on DB\n # layer you're using\n full_collection.drop(offset).take(PAGE_SIZE)\n end\n\n def count\n full_collection.count\n end\n\n def previous_link\n if offset > 0\n URITemplate.new(\"#{env['PATH_INFO']}{?offset}\").expand(offset: [offset - PAGE_SIZE, 0].max)\n end\n end\n\n def next_link\n if offset + page_size < count\n URITemplate.new(\"#{env['PATH_INFO']}{?offset}\").expand(offset: offset + PAGE_SIZE)\n end\n end\n end\nend\n```\n\nYou can pass this mapper explicitly when calling yaks:\n`yaks.call(collection, mapper: MyCollectionMapper)`, or leverage the\ndefault policy which gives you several options for hooking into mapper\nresolution.\n\n* When implementing a `CollectionMapper` inside your configured mapper\n namespace, or at the top level if no namespace is confgured, Yaks\n will use that instead of its vanilla collection mapper\n\n* If you're serializing collections of a specific type, you can implement a specific mapper for that. E.g. if you want paging for hypothetical `DatabaseQuerySet`, you can implement a `DatabaseQuerySetMapper`\n\n* You can make a `PagedCollection` decorator class, and provide a `PagedCollectionMapper`. This is a great pattern because you can put more of the paging logic inside that object, and override it in subclasses, e.g. to date per month, offset, page, etc.\n" }, { "path": "DEVELOPERS.md", "content": "# Yaks Dev Docs\n\nThis document is for when you want to hack on Yaks itself, or better\nunderstand its internals. To simply use it, consult the README.\n\n## Attribs\n\nYou'll find that most classes in Yaks include an instance of\n`Attribs`, for example\n\n``` ruby\nclass Yaks::Resource::Link\n include Attribs.new(:rel, :uri, options: {})\nend\n```\n\nYou can think of this (as a starting point) as replacing\n`attr_reader`, by adding this line instances of `Link` will have\ngetter methods for `rel`, `uri`, and `options`. But that's really just\nscratching the surface.\n\n`Attribs` relies on Anima, so you get the same things as\nusing `include Anima.new`\n\n* a hash-based constructor\n* getters\n* equality checks\n* `to_h`\n\n``` ruby\nlink = Yaks::Resource::Link.new(rel: :self, uri: '/api/cart', options: {templated: false})\n\nlink.rel # => :self\nlink.to_h # => {:rel=>:self, :uri=>\"/api/cart\", :options=>{:templated=>false}}\n\nlink == Yaks::Resource::Link.new(link.to_h) # => true\n```\n\nThese last two are important because they make these objects behave\nlike \"value objects\". They are fully defined by their properties, not\nby their (object) identity.\n\nNote that there are no setters, these objects are immutable.\n\nThere are some other things that `Attribs` adds that make it\na pleasure to work with these objects.\n\n* default values\n* `with` method to create updates\n* `with_x` convenience methods\n* `pp` method for representing instances as valid Ruby code\n* `append_to` method\n* `to_h_compact` method\n\nYou can include default values for properties in `Attribs.new(...)`, for example the options of a `Link` default to `{}`.\n\n`with` (see\n[this discussion](https://gist.github.com/plexus/42c6c9c63212182ee440)\nabout why that name was chosen), will create a new object, with\ncertain properties replaced.\n\n``` ruby\nlink2 = link.with(uri: '/foo/bar')\n\nlink # => #false}>\nlink2 # => #false}>\n```\n\nFor each property `foo` there's also `with_foo`, so `x.with(foo: 'bar')` is the same as `x.with_foo('bar')`\n\n`pp` recursively turns nested `Attribs` based objects into nicely\nformat, valid Ruby code. This is great for debugging, and very helpful\nwhen writing test cases.\n\n\n\n``` ruby\nclass FooMapper < Yaks::Mapper\n attributes :a, :b\n link :self, '/api/foo'\n has_many :baz\n form :bar do\n text :name\n text :age\n end\nend\n\nputs FooMapper.config.pp\n\n# -- output --\nYaks::Mapper::Config.new(\n attributes: [\n Yaks::Mapper::Attribute.new(name: :a),\n Yaks::Mapper::Attribute.new(name: :b)\n ],\n links: [\n Yaks::Mapper::Link.new(rel: :self, template: \"/api/foo\", options: {})\n ],\n associations: [\n Yaks::Mapper::HasMany.new(name: :baz, collection_mapper: nil)\n ],\n forms: [\n Yaks::Mapper::Form.new(\n config: Yaks::Mapper::Form::Config.new(\n name: :bar,\n fields: [\n Yaks::Mapper::Form::Field.new(name: :name, type: :text),\n Yaks::Mapper::Form::Field.new(name: :age, type: :text)\n ]\n )\n )\n ]\n)\n```\n\nBecause of the common case where new objects need to be added to a\nlist, e.g. a new link, association, form, to the respective property,\nthere's a `append_to` convenience method for that.\n\n``` ruby\nconfig = Yaks::Mapper::Config.new\nconfig = config.append_to(:attributes, Yaks::Mapper::Attribute.new(name: :a))\nconfig = config.append_to(:attributes, Yaks::Mapper::Attribute.new(name: :b))\nputs config.pp\n\n# -- output --\nYaks::Mapper::Config.new(\n attributes: [\n Yaks::Mapper::Attribute.new(name: {:name=>:a}),\n Yaks::Mapper::Attribute.new(name: {:name=>:b})\n ]\n)\n```\n\nFinally `to_h_compact` is similar to `to_h`, but won't output values that are the same as the defaults. So it's the minimal hash for which `foo == foo.class.new(foo.to_h_compact)` holds true.\n\n## The Mapper DSL\n\nNow that we know that most objects in Yaks behave in a uniform way, we\ncan leverage that to create the Yaks mapper DSL.\n\nAs demonstrated in the [example above](#mapper_config_example), most\nmethods like `link`, `has_many`, or `fieldset` simply instantiate an\nobject of a certain type, and add it to a \"config\" object. For a form\n`text` input field, the config object is a `Form::Config`, held by the\nform instance. At the top-level where we have attributes, links, and\nassociations, this config object is an instance of\n`Yaks::Mapper::Config` held by the mapper subclass. When configuring\nYaks itself (through `Yaks.new do ...`), you are creating a\n`Yaks::Config`, etc.\n\nBecause the objects created by the DSL all use `Attribs`,\ntheir constructor takes a Hash. For the DSL we often prefer positional\narguments, however. E.g. `form :create` instead of `form name:\n:create`. To bridge this gap classes like `Form` implement a class\nmethod `create`, with the same signature as the DSL method.\n\nBecause all these classes implement `create`, we can now generate the\nDSL methods in a generic way. This is where `Yaks::Configurable` comes\nin.\n\n## Yaks::Configurable\n\nHere's how `Yaks::Mapper` starts\n\n``` ruby\nmodule Yaks\n class Mapper\n extend Configurable\n\n def_add :link, create: Link, append_to: :links\n def_add :has_one, create: HasOne, append_to: :associations\n def_add :has_many, create: HasMany, append_to: :associations\n def_add :attribute, create: Attribute, append_to: :attributes\n def_add :form, create: Form, append_to: :forms\n\n def_set :type\n\n def_forward :attributes => :add_attributes\n def_forward :append_to\n```\n\nThe `def_add` \"macro\"[[1](#macro_footnote)] provided by `Yaks::Configurable` will generate a\nmethod which\n\n* creates an instance of certain class by calling `KlassName.create(...)`\n* update `config` to a new config which has the instance appended to\n `config.links`\n\nFor the case where a DSL method simply needs to overwrite a certain\nconfig attribute, use `def_set`.\n\nFor more involved cases you can implement methods on the Config object\nthat will \"update\" it in a specific way, returning the updated\ninstance (remember these are all immutable). In that case you generate\na DSL method which \"forwards\" to the config object, hence `def_forward`\n\n## Builder\n\nIn the case of `Yaks::Mapper`, the config object is stored on each\nmapper subclass. In other cases the configuration isn't class based\nthough, but instance based. For example, both a `Yaks::Form` and a\n`Yaks::Form::Fieldset` both have a `Yaks::Form::Config` instance as an\nattribute. Creating form fields will add them to this config.\n\nThe block passed to the `form` DSL method will be passed on to\n`Form.create`. Inside the block a very similar DSL is used as that on\na Mapper, but we don't have a class level evaluation context.\n\nInstead we create a `Yaks::Builder` and use the `Yaks::Configurable`\n\"macros\" to declare how the DSL in this context functions. Finally we\nask the builder to evaluate the block, updating the form's config.\n\n``` ruby\nmodule Yaks::Mapper::Form\n\n ConfigBuilder = Builder.new(Config) do\n def_set :action, :title, :method, :media_type\n def_add :field, create: Field::Builder, append_to: :fields\n def_add :fieldset, create: Fieldset, append_to: :fields\n # ...\n end\n\n def self.create(*args, &block)\n args, options = extract_options(args)\n options[:name] = args.first if args.first.is_a? Symbol\n\n config = Config.new(options)\n config = ConfigBuilder.build(config, &block)\n\n new(config: config)\n end\n\n # ...\nend\n```\n\nThe builder takes an initial config object, and then evaluates the\nblock, keeping track of the updated config as it evaluates DSL\nmethods. Finally you get the updated config object back. [[2](#state_monad_footnote)]\n\n\n### footnotes\n\n[1] I strongly dislike calling all Ruby\nclass-level methods \"macros\", especially when they have little to\nnothing in common with \"real\" (i.e. syntax tranforming read-time\nfunctions) macros. In this case what they achieve is very similar to\nwhat you would do with a \"real\" macro, so I'm rolling with it, adding\nsarcastic \"quotes\" to express my self-loathing in doing so.\n\n[2] You can think of the Builder as a\nstate monad. I'm sure that helps.\n" }, { "path": "FORMATS.org", "content": "#+TITLE:Comparison of Hypermedia Message Formats\n#+AUTHOR: Arne Brasseur\n#+email: arne@arnebrasseur.net\n#+INFOJS_OPT: view:info toc:nil\n#+BABEL: :session *ruby* :cache yes :results output graphics :exports both :tangle yes\n\n* Form Controls / Actions\n\n| Format | href | name/id | title/caption | method | media-type | fields | schema | string template | structured template |\n|-----------------+---------------------------------+----------+---------------+-----------+-----------------+----------------------------------+-------------+-----------------+---------------------|\n| HTML5 | action=\"\" | | | method=\"\" | enctype=\"\" | yes | | | |\n| halo | \"href\" | json key | | \"method\" | \"content-type\" | | \"schema\" | \"template\" | |\n| siren | \"href\" | \"name\" | \"title\" | \"method\" | \"type\" | \"fields\" | | | |\n| mason | \"href\" | json key | \"title\" | \"method\" | depends on type | | \"schemaUrl\" | | \"template\" |\n| Collection+JSON | \"href\" (query)/current resource | | \"prompt\" | | | | | | |\n| Hydra | current resource | \"@type\" | | \"method\" | | \"expects\": {\"supportedProperty\"} | | | |\n\n| Format | Name | Title | Type | Value |\n|-----------------+------------+----------+---------+---------|\n| Siren | \"name\" | | \"type\" | \"value\" |\n| Collection+JSON | \"name\" | \"prompt\" | | \"value\" |\n| Hydra | \"property\" | | \"range\" | |\n\n** HTML\n\n [[http://www.w3.org/TR/html5/forms.html][W3C: HTML5 Forms]]\n\n** halo+json\n\n [[https://gist.github.com/mikekelly/893552][Gist: A sketch of application/halo+json and application/halo+xml]]\n\n #+BEGIN_SRC json\n {\n \"_controls\": {\n \"widgetate\": {\n \"href\": \"/widget/{newID}\",\n \"method\": \"PUT\",\n \"content-type\": \"application/xml\",\n \"schema\": null,\n \"template\": \"\\\\n {{name}}\\\\n\\\\n \\\\n {{#blobs}}\\\\n \\\\n {{#first}}\\\\n true\\\\n {{/first}}\\\\n {{contents}}\\\\n \\\\n {{/blobs}}\\\\n \\\\n\\\\n {{#is_empty}}\\\\n This is an empty widget\\\\n {{/is_empty}}\\\\n\\\\n\"\n }\n }\n }\n #+END_SRC\n\n** Siren\n\n [[https://github.com/kevinswiber/siren][Siren Home page]]\n\n\n #+BEGIN_SRC json\n {\n \"actions\": [\n {\n \"name\": \"add-item\",\n \"title\": \"Add Item\",\n \"method\": \"POST\",\n \"href\": \"http://api.x.io/orders/42/items\",\n \"type\": \"application/x-www-form-urlencoded\",\n \"fields\": [\n { \"name\": \"orderNumber\", \"type\": \"hidden\", \"value\": \"42\" },\n { \"name\": \"productCode\", \"type\": \"text\" },\n { \"name\": \"quantity\", \"type\": \"number\" }\n ]\n }\n ]\n }\n #+END_SRC\n\n** Mason\n\n #+BEGIN_SRC json\n {\n \"@actions\": {\n \"is:delete-issue\": {\n \"type\": \"void\",\n \"href\": \"...\",\n \"method\": \"DELETE\",\n \"title\": \"Delete issue\"\n }\n }\n }\n #+END_SRC\n\n #+BEGIN_SRC json\n {\n \"@actions\": {\n // JSON action with schema reference\n \"is:project-create\": {\n \"type\": \"json\",\n \"href\": \"...\",\n \"title\": \"Create new project\",\n \"schemaUrl\": \"...\"\n },\n // JSON action with default template\n \"is:update-project\": {\n \"type\": \"json\",\n \"href\": \"...\",\n \"title\": \"Update project details\",\n \"template\": {\n \"Code\": \"SHOP\",\n \"Title\": \"Webshop\",\n \"Description\": \"All issues related to the webshop.\"\n }\n }\n }\n }\n #+END_SRC\n\n\nhttps://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-1.md#actions\n** Collection+JSON\n\n CJ does not have a form-like representation. It does allow\n resources to contain a \"template\", which is really a list of form\n fields, and a client can use HTTP methods against the same endpoint\n to perform CRUD operations. In addition CJ provides \"queries\" for\n basic GET based operations.\n\n #+BEGIN_SRC json\n {\n \"template\" :\n {\n \"data\" :\n [\n {\"prompt\" : STRING, \"name\" : STRING, \"value\" : VALUE},\n {\"prompt\" : STRING, \"name\" : STRING, \"value\" : VALUE},\n ...\n {\"prompt\" : STRING, \"name\" : STRING, \"value\" : VALUE}\n ]\n }\n }\n #+END_SRC\n\n #+BEGIN_SRC json\n {\n \"queries\" :\n [\n {\n \"href\" : \"http://example.org/search\",\n \"rel\" : \"search\",\n \"prompt\" : \"Enter search string\",\n \"data\" :\n [\n {\"name\" : \"search\", \"value\" : \"\"}\n ]\n }\n ]\n }\n #+END_SRC\n** JSON-LD + Hydra\n\n Example taken from [[http://sookocheff.com/posts/2014-03-11-on-choosing-a-hypermedia-format/][this blog post]]\n\n JSON-LD itself does not have form like controls, only\n linking. Hydra introduces an \"operation\" property for this purpose.\n\n #+BEGIN_SRC json\n {\n \"@context\": [\n \"http://www.w3.org/ns/hydra/core\",\n {\n \"@vocab\": \"https://schema.org/\",\n \"image\": { \"@type\": \"@id\" },\n \"friends\": { \"@type\": \"@id\" }\n }\n ],\n \"@id\": \"https://api.example.com/player/1234567890/friends\",\n \"operation\": {\n \"@type\": \"BefriendAction\",\n \"method\": \"POST\",\n \"expects\": {\n \"@id\": \"http://schema.org/Person\",\n \"supportedProperty\": [\n { \"property\": \"name\", \"range\": \"Text\" },\n { \"property\": \"alternateName\", \"range\": \"Text\" },\n { \"property\": \"image\", \"range\": \"URL\" }\n ]\n }\n }\n }\n #+END_SRC\n" }, { "path": "Gemfile", "content": "source 'https://rubygems.org'\n\ngemspec path: 'yaks'\ngemspec path: 'yaks-html'\ngemspec path: 'yaks-sinatra'\n\n# Transit depends on Oj, which is not available for JRuby\nunless defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'\n gemspec path: 'yaks-transit'\nend\n\nif RUBY_VERSION < '2'\n gem 'mime-types', [ '>= 2.6.2', '< 3' ]\nend\n\n# gem 'mutant', github: 'mbj/mutant'\n# gem 'mutant-rspec', github: 'mbj/mutant'\n" }, { "path": "IDENTIFIERS.md", "content": "# Identifiers\n\nIn Yaks, and Hypermedia message formats in general, a number of\ndifferent types of identifiers are used. Some are full URIs and\ncorrespond with well defined specs. Some are just short identifers\nthat are easy to program with.\n\nUnderstanding these types of identifiers is key to creating a unifying\nmodel of a \"Resource\" that can be shared across output formats. We\nwant to unify as much as possible across formats, without conflating\nthings that are really not the same.\n\nThis document reflects my current limited understanding of things,\nbased on possibly incorrect assumptions. Feedback is more than\nwelcome.\n\n## rels\n\nAs used in HTML and Atom, these identifiers say what the relationship\nis between a resource and another resource it links to. There is a\n[registry of names](http://www.iana.org/assignments/link-relations/link-relations.xhtml),\ne.g. self, next, profile, stylesheet. Custom rels need to be fully\nqualified URLs. Keep in mind that these are simply opaque identifiers,\nbut by using a known protocol like http they can be used to point at\ndocumentation.\n\nSome examples\n\n```\ncopyright\nstylesheet\nhttp://api.example.com/rel/author\nhttp://api.example.com/api-docs/relationships#comment\ncustom_scheme:foo\n/order\n```\n\nThe last example is a relative URL, which would have to be expanded against the source URL of the document it is mentioned in.\n\nIn Yaks both links and subresources are specified with their rel(ationship).\n\n```ruby\nclass PersonMapper < Yaks::Mapper\n link :self, '/people/{id}'\n link 'http://api.example.com/rels#friends', '/people/{id}/friends'\n\n has_one :address, rel: 'http://api.example.com/rels#address'\nend\n```\n\nFor subresources the rel can be omitted, in which case it will be inferred based on the rel_template:\n\n```ruby\n$yaks = Yaks.new do\n rel_template 'http://api.example.com/rels/{dest}'\nend\n```\n\nLinks and subresources are rendered keyed by rel in HAL and Collection+JSON. JSON-API renders `self` links as the `href` of a resource.\n\n## profiles\n\nA specific IANA registered rel type is profile.\n\n> Profile: Identifying that a resource representation conforms to a certain profile, without affecting the non-profile semantics of the resource representation.\n\nProfile basically adds a layer of semantics on top of the hypermedia message format (e.g. HAL, Collection+JSON), which in turns defines semantics on top of a serialization format (JSON, XML, EDN). Loosely speaking it could be seen as the \"type\" or \"class\". For example if you know the profile of a resource, you might know you can expect to find a \"name\", \"date_of_birth\", or \"post_body\" field.\n\n## \"type\"\n\nDespite the appealing rigor of having fully qualified URIs to identify things, sometimes you just want to call a person a `person`. In Yaks we call these short identifier the *type* for lack of a better word. In some cases, notably JSON-API, they are used literally in the output. More often they are used to derive full URIs based on a template.\n\nThe type of a mapper is inferred from its class name, but can be set explicitly as well.\n\n```ruby\nclass CatMapper < Yaks::Mapper\nend\n\n# type = \"cat\"\n```\n\n```ruby\nclass CatMapper < Yaks::Mapper\n type 'feline'\nend\n\n# type => \"feline\"\n```\n\n## rdf class\n\nRDF (Resource Description Framework) is a set of specifications for use in \"semantic web\" applications. RDF is based on \"ontologies\" that precisely define a \"vocabulary\" of \"classes\" and \"predicates\". An example class identifier for all Merlot wines could be\n\n> http://www.w3.org/TR/2004/REC-owl-guide-20040210/wine#Merlot\n\n(source [wikipedia](http://en.wikipedia.org/wiki/Resource_Description_Framework))\n\nNot currently used by Yaks, but might become important when implementing support for JSON-LD or other RDF serialization formats.\n\n## CURIES\n\nCURIES are \"compact uris\". The HAL format uses this so it can have the rigor of fully specified rels, with the ease of use of short-name \"type\" identifiers. The mechanism is similar to how one specifies and uses XML namespaces.\n\nFrom the HAL spec:\n\n```json\n{\n \"_links\": {\n \"self\": { \"href\": \"/orders\" },\n \"curies\": [{ \"name\": \"ea\", \"href\": \"http://example.com/docs/rels/{rel}\", \"templated\": true }],\n \"next\": { \"href\": \"/orders?page=2\" },\n \"ea:find\": {\n \"href\": \"/orders{?id}\",\n \"templated\": true\n },\n \"ea:admin\": [{\n \"href\": \"/admins/2\",\n \"title\": \"Fred\"\n }, {\n \"href\": \"/admins/5\",\n \"title\": \"Kate\"\n }]\n }\n}\n```\n\nIn this case \"ea:find\" is just a shorthand for \"http://example.com/docs/rels/find\".\n" }, { "path": "LICENSE", "content": "Copyright (c) 2013-2014 Arne Brasseur\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n" }, { "path": "Rakefile", "content": "require 'yaks'\nrequire 'yaks-html'\nrequire 'yaks-sinatra'\nrequire 'yaks-transit'\n\nrequire 'rspec/core/rake_task'\nrequire 'rubocop/rake_task'\nrequire 'rubygems/package_task'\nrequire 'yard'\n\ndef delegate_task(gem, task_name)\n task task_name do\n chdir gem.to_s do\n sh \"rake\", task_name.to_s\n end\n end\nend\n\n[:yaks, :\"yaks-html\", :\"yaks-sinatra\"].each do |gem|\n namespace gem do\n desc 'Run rspec'\n delegate_task gem, :rspec\n\n desc 'Build gem'\n delegate_task gem, :gem\n\n desc 'Generate YARD docs'\n delegate_task gem, :yard\n\n desc 'push gem to rubygems'\n task :push => \"#{gem}:gem\" do\n sh \"gem push pkg/#{gem}-#{Yaks::VERSION}.gem\"\n end\n end\nend\n\ndesc \"Tag current release and push to Github\"\ntask :tag do\n sh \"git tag v#{Yaks::VERSION}\"\n sh \"git push --tags\"\nend\n\ndesc \"Tag, build, and push all gems to rubygems.org\"\ntask :push_all => [\n :tag,\n \"yaks:gem\",\n \"yaks-html:gem\",\n \"yaks-sinatra:gem\",\n \"yaks:push\",\n \"yaks-html:push\",\n \"yaks-sinatra:push\"\n ]\ntask :push => :push_all\n\ndesc \"Run all the tests\"\ntask :rspec => [\"yaks:rspec\", \"yaks-html:rspec\", \"yaks-sinatra:rspec\"]\n\ndesc 'Run mutation tests'\ndelegate_task :yaks, :mutant\n\ndesc \"Start a console\"\ntask :console do\n require 'irb'\n require 'irb/completion'\n ARGV.clear\n IRB.start\nend\n\ntask :ataru do\n require \"ataru\"\n Dir.chdir(\"yaks\")\n Ataru::CLI::Application.start([\"check\", \"README.md\"])\nend\n\nRuboCop::RakeTask.new do |task|\n task.options << '--display-cop-names'\nend\n\ntask :default => [:rspec, :rubocop]\n" }, { "path": "bench/bench.rb", "content": "\nrequire 'benchmark/ips'\nrequire 'yaks'\n\nrequire_relative '../spec/acceptance/models'\nrequire_relative '../spec/fixture_helpers'\n\nBenchmark.ips do |x|\n $yaks = Yaks.new\n\n input = FixtureHelpers.load_yaml_fixture 'confucius'\n\n x.report \"Simple HAL mapping\" do\n $yaks.serialize(input)\n end\nend\n" }, { "path": "bench/bench_1000.rb", "content": "#!/usr/bin/env ruby\n\nrequire 'English'\nrequire 'benchmark/ips'\nrequire 'ruby-prof'\nrequire 'yaks'\n\nSIZE = 20\n$timestamp = Time.now.utc.iso8601.gsub('-', '').gsub(':', '')\n$yaks = Yaks.new\n\nFlatModel = Struct.new(:field1, :field2)\nDeepModel = Struct.new(:field, :next)\n\nflat = SIZE.times.map do |i|\n FlatModel.new(i, 'x' * (i % 50))\nend\n\ndeep = nil\nSIZE.times do |i|\n deep = DeepModel.new(i, deep)\nend\n\nclass FlatMapper < Yaks::Mapper\n attributes :field1, :field2\n link :self, '/model/{field1}'\nend\n\nclass DeepMapper < Yaks::Mapper\n attributes :field\n link :self, '/model/{field}'\n has_one :next, mapper: DeepMapper\nend\n\ndef profile!(name)\n RubyProf.start\n yield\n results = RubyProf.stop\n File.open \"/tmp/#{name}-#{$timestamp}.out.#{$PROCESS_ID}\", 'w' do |file|\n RubyProf::CallTreePrinter.new(results).print(file)\n end\nend\n\ndo_flat = ->(format) { -> { $yaks.serialize(flat, item_mapper: FlatMapper, format: format) } }\ndo_deep = ->(format) { -> { $yaks.serialize(deep, mapper: DeepMapper, format: format) } }\n\n10.times { do_flat[:hal][] }\n10.times { do_deep[:hal][] }\n\nprofile!('flat', &do_flat.(:hal))\nprofile!('deep', &do_deep.(:hal))\nexit\n\nBenchmark.ips(10) do |job|\n Yaks::Format.names.each do |format|\n job.report \"#{format} ; #{SIZE} objects in a list ; no nesting\", &do_flat.(format)\n job.report \"#{format} ; #{SIZE} objects nested\", &do_deep.(format)\n end\nend\n" }, { "path": "code_of_conduct.md", "content": "# Contributor Code of Conduct\n\nAs contributors and maintainers of this project, we pledge to respect\nall people who contribute through reporting issues, posting feature\nrequests, updating documentation, submitting pull requests or patches,\nand other activities.\n\nWe are committed to making participation in this project a\nharassment-free experience for everyone, regardless of level of\nexperience, gender, gender identity and expression, sexual\norientation, disability, personal appearance, body size, race, age, or\nreligion.\n\nExamples of unacceptable behavior by participants include the use of\nsexual language or imagery, derogatory comments or personal attacks,\ntrolling, public or private harassment, insults, or other\nunprofessional conduct.\n\nProject maintainers have the right and responsibility to remove, edit,\nor reject comments, commits, code, wiki edits, issues, and other\ncontributions that are not aligned to this Code of Conduct. Project\nmaintainers who do not follow the Code of Conduct may be removed from\nthe project team.\n\nInstances of abusive, harassing, or otherwise unacceptable behavior\nmay be reported by opening an issue or contacting one or more of the\nproject maintainers.\n\nThis Code of Conduct is adapted from the\n[Contributor Covenant](http:contributor-covenant.org), version 1.0.0,\navailable at\n[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)" }, { "path": "notes.org", "content": "0.4\n\n* DONE Get rid of profile/rel registry, use policy instead\n* DONE pass around policy explicitly instead of through options\n* DONE introduce name/type separate from profile\n** DONE mapper\n** DONE Resource\n* DONE allow setting rel types directly on associations, with fallback to policy\n* DONE switch to hash-based init of Resource to make it more extensible\n* DONE add Resource#type\n* DONE not 100% happy yet about nameing of mapper#mapper_name / config#name. Maybe use `type` across the board?\n* DONE Fix JsonAPISerializer\n* top-level automatic links, e.g. for self and profile\n* make HAL plural/singular links configurable from the Yaks.new\n* make primitivize configuration instance based, not global\n* Have JsonApi add self links as href: attributes\n* Move examples to acceptance tests\n* Select mapper based on content type\n* move to 100% mutcov\n\npre 0.5\n\n* CURIES/namespaces\n\nTicketsolve::Api::Yaks = ::Yaks.new do\n policy do\n def derive...\n end\n\n hal_options.plural_link '...'\n\n primitivize Date, Time do |o|\n o.iso8601\n end\n\n rel_template \"http://literature.example.com/rel/#{association_name}\"\n\n link :self, \"http://api.com/{key}/{id}\"\n link :profile, \"http://api.com/profile/{key}\"\n\n # and/or\n derive_rel_from_association do |mapper, association|\n \"http://literature.example.com/rel/#{association.name}\"\n end\nend\n\n\n\n* DONE 59 lib/yaks/mapper.rb\n* DONE 92 lib/yaks/mapper/link.rb\n* DONE 37 lib/yaks/mapper/association.rb\n* DONE 3 lib/yaks/version.rb\n* DONE 13 lib/yaks/mapper/has_many.rb\n* DONE 9 lib/yaks/mapper/has_one.rb\n* DONE 79 lib/yaks/config.rb\n* 79 lib/yaks/mapper/config.rb\n* 73 lib/yaks.rb\n* DONE 72 lib/yaks/util.rb\n* DONE 65 lib/yaks/collection_resource.rb\n* 59 lib/yaks/json_api_serializer.rb\n* 59 lib/yaks/hal_serializer.rb\n* 43 lib/yaks/primitivize.rb\n* 37 lib/yaks/mapper/class_methods.rb\n* DONE 33 lib/yaks/collection_mapper.rb\n* 28 lib/yaks/null_resource.rb\n* DONE 27 lib/yaks/resource.rb\n* 25 lib/yaks/resource/link.rb\n* DONE 23 lib/yaks/fp.rb\n* 22 lib/yaks/serializer.rb\n* 15 lib/yaks/shared_options.rb\n* 15 lib/yaks/default_policy.rb\n* 10 lib/yaks/mapper/map_links.rb\n\nhttp://www.dragoart.com/tuts/4344/1/1/how-to-draw-a-yak.htm\nhttps://www.google.com/search?q=yak+head&num=20&source=lnms&tbm=isch&sa=X&ei=uVoAVbyWLcTiO-v0gYgF&ved=0CAcQ_AUoAQ&biw=1758&bih=923&dpr=1.09#imgdii=_&imgrc=CtgMobmQThXw_M%253A%3BzyYGcwgq1IAU_M%3Bhttps%253A%252F%252Fcallaocafeandmarket.files.wordpress.com%252F2014%252F02%252Fyak2.jpg%3Bhttps%253A%252F%252Fcallaocafeandmarket.wordpress.com%252Fweather%252F%3B563%3B539\nhttps://www.google.com/search?q=hair+over+eyes&num=20&source=lnms&tbm=isch&sa=X&ei=p2sBVajOOIKvPdDjgPgL&ved=0CAcQ_AUoAQ&biw=1758&bih=923&dpr=1.09#imgdii=_&imgrc=la9hTGBvOniv9M%253A%3B_nu4vLbBOXzIeM%3Bhttp%253A%252F%252Fwww.rampantscotland.com%252Fdiary%252Fgraphics%252Fhighland_cow_baldernock_x3481d.jpg%3Bhttp%253A%252F%252Fwww.rampantscotland.com%252Fdiary%252Fdiary_photos_july11b.htm%3B514%3B496\nhttps://www.google.com/search?q=hair+over+eyes&num=20&source=lnms&tbm=isch&sa=X&ei=p2sBVajOOIKvPdDjgPgL&ved=0CAcQ_AUoAQ&biw=1758&bih=923&dpr=1.09#imgdii=_&imgrc=RmzHL5NICZcanM%253A%3BwMr__Up6S7s_9M%3Bhttp%253A%252F%252Fwww.peakdistrictonline.co.uk%252Fimages%252Fwildlife%252Fanimals%252FHighland_Cattle_In_The_Peak_District_5.jpg%3Bhttp%253A%252F%252Fwww.peakdistrictonline.co.uk%252Ffarm-animals-highland-cattle-c101118.html%3B620%3B412\nhttps://www.google.com/search?biw=1758&bih=923&tbm=isch&sa=1&q=yak+horns&oq=yak+horns&gs_l=img.3..0j0i24.118958.120138.0.120293.9.8.0.1.1.0.142.713.6j2.8.0.msedr...0...1c.1.62.img..0.9.701.rHB0v54VT9k#imgdii=_&imgrc=c8D4U_x1gob0YM%253A%3BzvdhmtL1g8r_UM%3Bhttp%253A%252F%252F4.bp.blogspot.com%252F_2Sr5OicZPHQ%252FTFT2H5ViKWI%252FAAAAAAAAAFs%252FfYlG-en9mFk%252Fs1600%252Fyak%252Band%252BDri.jpg%3Bhttp%253A%252F%252Fthewodakpa.blogspot.com%252F2010%252F07%252Ftibetan-yak_29.html%3B1080%3B672\nhttps://www.google.com/search?biw=1758&bih=923&tbm=isch&sa=1&q=yak+horns&oq=yak+horns&gs_l=img.3..0j0i24.118958.120138.0.120293.9.8.0.1.1.0.142.713.6j2.8.0.msedr...0...1c.1.62.img..0.9.701.rHB0v54VT9k#imgdii=_&imgrc=_N83z2DYkcc7DM%253A%3BDV8K7BLZksSGrM%3Bhttp%253A%252F%252Fthumbs.dreamstime.com%252Fz%252Fyak-stuffed-animal-like-bull-23182676.jpg%3Bhttp%253A%252F%252Fwww.dreamstime.com%252Froyalty-free-stock-image-yak-stuffed-animal-like-bull-image23182676%3B1300%3B957\n\n\n* JSON-LD / RDF\n** Useful protocols used in RDF.rb\n\n - to_rdf, to_uri\n - RDF::URI pname, qname\n - RDF::Vocabulary::Term\n\nhttp://ruby-rdf.github.io/\nhttps://github.com/ruby-rdf/json-ld/\nhttp://schema.org/MusicEvent\nhttps://developers.google.com/structured-data/events/venues\nhttp://json-ld.org/playground/index.html\n\n\n http://www.iana.org/assignments/relation/\n http://microformats.org/wiki/rel- and http://microformats.org/profile/\n" }, { "path": "shared/rake_tasks.rb", "content": "require 'yaks'\nrequire 'yaks-html'\nrequire 'rubygems/package_task'\nrequire 'rspec/core/rake_task'\nrequire 'yard'\n\ndef mutant_task(_gem)\n require 'mutant'\n task :mutant do\n pattern = ENV.fetch('PATTERN', 'Yaks*')\n opts = ENV.fetch('MUTANT_OPTS', '').split(' ')\n requires = %w[-ryaks -ryaks/behaviour/optional_includes]\n args = %w[-Ilib --use rspec --score 100] + requires + opts + [pattern]\n result = Mutant::CLI.run(args)\n raise unless result == Mutant::CLI::EXIT_SUCCESS\n end\nend\n\ndef gem_tasks(gem)\n Gem::PackageTask.new(Gem::Specification.load(\"#{gem}.gemspec\")) do |task|\n task.package_dir = '../pkg'\n end\n\n mutant_task(gem) if RUBY_ENGINE == 'ruby' && RUBY_VERSION >= \"2.1.0\"\n\n RSpec::Core::RakeTask.new(:rspec) do |t, _task_args|\n t.rspec_opts = \"-Ispec\"\n t.pattern = \"spec\"\n end\n\n YARD::Rake::YardocTask.new do |t|\n t.files = [\"lib/**/*.rb\" \"**/*.md\"]\n t.options = %w[--output-dir ../doc]\n end\nend\n" }, { "path": "shared/rspec_config.rb", "content": "require 'rspec/its'\nrequire 'bogus/rspec'\nrequire 'timeout'\n\n# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration\n\nRSpec.configure do |rspec|\n # Set the FULLSTACK environment variable to prevent RSpec from\n # filtering stack traces. This can be useful to debug errors that\n # happen inside third party libraries\n rspec.backtrace_exclusion_patterns = [] if ENV['FULLSTACK']\n\n # Limits the available syntax to the non-monkey patched syntax that is\n # recommended. For more details, see:\n # - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax\n # - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/\n # - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching\n rspec.disable_monkey_patching!\n\n # Make sure we stay up to date\n rspec.raise_errors_for_deprecations!\n\n rspec.expect_with :rspec do |expectations|\n # This option will default to `true` in RSpec 4. It makes the `description`\n # and `failure_message` of custom matchers include text for helper methods\n # defined using `chain`, e.g.:\n # be_bigger_than(2).and_smaller_than(4).description\n # # => \"be bigger than 2 and smaller than 4\"\n # ...rather than:\n # # => \"be bigger than 2\"\n expectations.include_chain_clauses_in_custom_matcher_descriptions = true\n end\n\n # This is configured for us by including bogus/rspec. We do not include rspec-mocks.\n # rspec.mock_with :bogus\n\n # Mutated code can lead to infinite loops. Consider tests that run\n # too long as having failed\n if defined?(Mutant)\n rspec.around(:each) do |example|\n Timeout.timeout(1, &example)\n end\n end\nend\n" }, { "path": "yaks/.rspec", "content": "-r spec_helper" }, { "path": "yaks/README.md", "content": "[![Gem Version](https://badge.fury.io/rb/yaks.png)][gem]\n[![Build Status](https://secure.travis-ci.org/plexus/yaks.png?branch=master)][travis]\n[![Code Climate](https://codeclimate.com/github/plexus/yaks.png)][codeclimate]\n[![Gitter](https://badges.gitter.im/Join Chat.svg)][gitter]\n\n[gem]: https://rubygems.org/gems/yaks\n[travis]: https://travis-ci.org/plexus/yaks\n[codeclimate]: https://codeclimate.com/github/plexus/yaks\n[gitter]: https://gitter.im/plexus/yaks?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\n# Yaks\n\n\n\nThe library that understands hypermedia.\n\n**If you use Yaks please help out by filling out the [Yaks Users Survey](https://docs.google.com/forms/d/1sZB03Vf32igmNmJ7RP8mo8H4VZHcVIpSrUSbvx2xD8s/viewform)**\n\nYaks takes your data and transforms it into hypermedia formats such as\nHAL, JSON-API, or HTML. It allows you to build APIs that are\ndiscoverable and browsable. It is built from the ground up around\nlinked resources, a concept central to the architecture of the web.\n\nYaks consists of a resource representation that is independent of any\noutput type. A Yaks mapper transforms an object into a resource, which\ncan then be serialized into whichever output format the client\nrequested. These formats are presently supported:\n\n* HAL\n* JSON API\n* Collection+JSON\n* HTML\n* HALO\n* Transit\n\n## Table of Contents\n\n- [State of Development](#user-content-state-of-development)\n- [Concepts](#user-content-concepts)\n- [Mappers](#user-content-mappers)\n - [Attributes](#user-content-attributes)\n - [Forms](#user-content-forms)\n - [Filtering](#user-content-filtering)\n - [Links](#user-content-links)\n - [Associations](#user-content-associations)\n - [Behaviours](#user-content-behaviours)\n- [Calling Yaks](#user-content-calling-yaks)\n - [Rack env](#user-content-rack-env)\n- [Namespace](#user-content-namespace)\n- [Custom attribute/link/subresource handling](#user-content-custom-attributelinksubresource-handling)\n- [Resources, Formatters, Serializers](#user-content-resources-formatters-serializers)\n- [Formats](#user-content-formats)\n - [HAL](#user-content-hal)\n - [HTML](#user-content-html)\n - [JSON-API](#user-content-json-api)\n - [Collection+JSON](#user-content-collection-json)\n - [Transit](#user-content-transit)\n- [Hooks](#user-content-hooks)\n- [Policy over Configuration](#user-content-policy-over-configuration)\n - [derive_mapper_from_object](#user-content-derive_mapper_from_object)\n - [derive_mapper_from_association](#user-content-derive_mapper_from_association)\n - [derive_rel_from_association](#user-content-derive_rel_from_association)\n- [Primitivizer](#user-content-primitivizer)\n- [Integration](#user-content-integration)\n- [Real World Usage](#user-content-real-world-usage)\n- [Demo](#user-content-demo)\n- [Cookbook](#user-content-cookbook)\n- [Standards Based](#user-content-standards-based)\n- [How to contribute](#user-content-how-to-contribute)\n- [License](#user-content-license)\n\n## Packages\n\n- [yaks-sinatra](yaks-sinatra/README.md)\n- [yaks-html](yaks-html/README.md)\n- [yaks-transit](yaks-transit/README.md)\n\n## State of Development\n\nRecent focus has been on stabilizing the core classes, improving\nformat support, and increasing test (mutation) coverage. We are\ncommitted to a stable public API and semantic version. On the 0.x line\nthe minor version is bumped when non-backwards compatible changes are\nintroduced. After 1.x regular semver conventions will be used.\n\n## Concepts\n\nYaks is a processing pipeline, you create and configure the pipeline,\nthen feed data through it.\n\n``` ruby\nyaks = Yaks.new do\n default_format :hal\n rel_template 'http://api.example.com/rels/{rel}'\n format_options(:hal, plural_links: [:copyright])\n mapper_namespace ::MyAPI\n json_serializer do |data|\n JSON.dump(data)\n end\nend\n\nyaks.call(product)\n```\n\nYaks performs this serialization in three steps\n\n* It *maps* your data to a `Yaks::Resource`\n* It *formats* the resource to a syntax tree representation\n* It *serializes* to get the final output\n\nFor JSON types, the \"syntax tree\" is just a combination of Ruby primitives, nested arrays and hashes with strings, numbers, booleans, nils.\n\nA Resource is an abstraction shared by all output formats. It can contain key-value attributes, RFC5988 style links, and embedded sub-resources.\n\nTo build an API you create a \"mapper\" for each type of object you want to represent. Yaks takes care of the rest.\n\nFor all configuration options see [Yaks::Config::DSL](http://rdoc.info/gems/yaks/frames/Yaks/Config/DSL).\n\nSee also the [API Docs on rdoc.info](http://rdoc.info/gems/yaks/frames/file/README.md)\n\n## Mappers\n\nSay your app has a `Post` object for blog posts. To serve posts over your API, define a `PostMapper`\n\n```ruby\nclass PostMapper < Yaks::Mapper\n link :self, '/api/posts/{id}'\n\n attributes :id, :title\n\n has_one :author\n has_many :comments\nend\n```\n\nConfigure a Yaks instance and start serializing!\n\n```ruby\nyaks = Yaks.new\nyaks.call(post)\n```\n\nor a bit more elaborate\n\n```ruby\nyaks = Yaks.new do\n default_format :json_api\n rel_template 'http://api.example.com/rels/{rel}'\n format_options(:hal, plural_links: [:copyright])\nend\n\nyaks.call(post, mapper: ::PostMapper, format: :hal)\n```\n\n### Attributes\n\nUse the `attribute` or `attributes` DSL methods to specify which attributes of your model you want to expose, as in the example above. You can override the `load_attribute` method to change how attributes are fetched from the model.\n\nFor example, if you are representing data that is stored in a Hash, you could do\n\n```ruby\nclass PostHashMapper < Yaks::Mapper\n attributes :id, :body\n\n # @param name [Symbol]\n def load_attribute(name)\n object[name]\n end\nend\n```\nThe `attribute` method may also take a block that will be called with the context of the mapper instance. The default implementation will use the block if provided, otherwise it will first try to find a matching method for an attribute on the mapper itself, and will then fall back to calling the actual model. So you can add extra 'virtual' attributes like so :\n\n```ruby\nclass CommentMapper < Yaks::Mapper\n attributes :body, :date\n attribute :id do\n \"Id-#{object.id}\"\n end\n\n def date\n object.created_at.strftime(\"at %I:%M%p\")\n end\nend\n```\n\n### Forms\n\nMapper can contain form defintions, for formats that support them. The\nform DSL mimics the HTML5 field and attribute names.\n\n```ruby\nclass PostMapper < Yaks::Mapper\n attributes :id, :body, :date\n\n form :add_comment do\n action '/api/comments'\n method 'POST'\n media_type 'application/json'\n\n text :body\n hidden :post_id, value: -> { object.id }\n end\nend\n```\n\nTODO: add more info on form element types, attributes, conditional\nrendering of forms, dynamic form sections, ...\n\n\n#### Filtering\n\nYou can override `#attributes`, or `#associations`.\n\n```ruby\nclass SongMapper < Yaks::Mapper\n attributes :title, :duration, :lyrics\n\n has_one :artist\n has_one :album\n\n def minimal?\n env['HTTP_PREFER'] =~ /minimal/\n end\n\n # @return Array\n def attributes\n return super.reject {|attr| attr.name.equal? :lyrics } if minimal?\n super\n end\n\n # @return Array\n def associations\n return [] if minimal?\n super\n end\nend\n```\n\n### Links\n\nYou can specify link templates that will be expanded with model attributes. The link relation name should be a registered [IANA link relation](http://www.iana.org/assignments/link-relations/link-relations.xhtml) or a URL. The template syntax follows [RFC6570 URI templates](http://tools.ietf.org/html/rfc6570).\n\n```ruby\nclass FooMapper < Yaks::Mapper\n link :self, '/api/foo/{id}'\n link 'http://api.foo.com/rels/comments', '/api/foo/{id}/comments'\nend\n```\n\nTo prevent a link to be expanded, add `expand: false` as an option. Now the actual template will be rendered in the result, so clients can use it to generate links from.\n\nTo partially expand the template, pass an array with field names to expand. e.g.\n\n```ruby\nclass ProductMapper < Yaks::Mapper\n link 'http://api.foo.com/rels/line_item', '/api/line_items?product_id={product_id}&quantity={quantity}', expand: [:product_id]\nend\n\n# \"_links\": {\n# \"http://api.foo.com/rels/line_item\": {\n# \"href\": \"/api/line_items?product_id=273&quantity={quantity}\",\n# \"templated\": true\n# }\n# }\n\n```\n\nYou can pass a proc instead of a template, in that case the proc will\nbe resolved in the context of the mapper. What this means is that, if\nthe proc takes no arguments, it will be evaluated with the mapper\ninstance as the value of `self`. If the proc does take an argument,\nthen it will receive the mapper instance, and will be evaluated as a\nclosure, i.e. with access to the scope in which it was defined.\n\n```ruby\nclass FooMapper < Yaks::Mapper\n link 'http://api.foo.com/rels/go_home', -> { home_url }\n # by default calls object.home_url\n\n def home_url\n object.setting('home_url')\n end\nend\n```\n\n\nTo only include links based on certain conditions, add an `:if`\noption, passing it a block. The block will be resolved in the context\nof the mapper, as explained before.\n\nFor example, say you want to notify the consumer of your API that upon\nconfirming an order, the previously held cart is no longer valid, you\ncould use the IANA standard `invalidates` rel to communicate this.\n\n``` ruby\nclass OrderMapper < Yaks::Mapper\n link :invalidates, '/api/cart', if: ->{ env['api.invalidate_cart'] }\nend\n```\n\n### Associations\n\nUse `has_one` for an association that returns a single object, or `has_many` for embedding a collection.\n\nOptions\n\n* `:mapper` : Use a specific for each instance, will be derived from the class name if omitted (see Policy vs Configuration)\n* `:collection_mapper` : For mapping the collection as a whole, this defaults to Yaks::CollectionMapper, but you can subclass it for example to add links or attributes on the collection itself\n* `:rel` : Set the relation (symbol or URI) this association has with the object. Will be derived from the association name and the configured rel_template if ommitted\n* `:if`: Only render the association if a condition holds\n* `:link_if`: Conditionally render the association as a link. A `:href` option is required\n\n```ruby\nclass ShowMapper < Yaks::Mapper\n has_many :events, href: '/show/{id}/events', link_if: ->{ events.count > 50 }\nend\n```\n\n### Behaviours\n\nYaks provides mixins to change how your mappers work. These need to be\nrequired separately, they are not loaded by default.\n\n#### OptionalIncludes\n\nYou may choose to not render associations by default, but to only do\nso when the client explicitly asks for them. This can be done by\nincluding `Yaks::Behaviour::OptionalIncludes`.\n\nWhich associations to load is specified with the the `include` query\nparameter. You can use dots to load nested associated.\n\n```ruby\nrequire \"yaks/behaviour/optional_includes\"\n\nclass PostMapper < Yaks::Mapper\n include Yaks::Behaviour::OptionalIncludes\n\n has_one :author\n has_many :comments\nend\n\nclass AuthorMapper < Yaks::Mapper\n include Yaks::Behaviour::OptionalIncludes\n\n has_one :profile\nend\n```\n\n```\nGET /post/42?include=comments,author.profile\n```\n\nNote that this will only work when Yaks has access to the Rack\nenvironment. When using an existing integration like `yaks-sinatra`\nthis will be handled for you.\n\nTo force an association to always be included, override its `if`\ncondition to always return true.\n\n```ruby\nrequire \"yaks/behaviour/optional_includes\"\n\nclass PostMapper < Yaks::Mapper\n include Yaks::Behaviour::OptionalIncludes\n\n has_one :author\n has_many :comments, if: ->{ true }\nend\n```\n\n## Calling Yaks\n\nOnce you have a Yaks instance, you can call it with `call`\n(`serialize` also works but might be deprecated in the future.) Pass\nit the data to be serialized, plus options.\n\n* `:env` a Rack environment, see next section\n* `:format` the format to be used, e.g. `:json_api`. Note that if the Rack env contains an `Accept` header which resolves to a recognized format, then the header takes precedence\n* `:mapper` the mapper to be used. Will be inferred if omitted\n* `:item_mapper` When rendering a collection, the mapper to be used for each item in the collection. Will be inferred from the class of the first item in the collection if omitted.\n\n### Rack env\n\nWhen serializing, Yaks lets you pass in an `env` hash, which will be made available to all mappers.\n\n```ruby\nclass FooMapper < Yaks::Mapper\n attributes :bar\n\n def bar\n if env['something']\n #...\n end\n end\nend\n\nyaks = Yaks.new\nyaks.call(foo, env: my_env)\n```\n\nThe env hash will be available to all mappers, so you can use this to\npass around context. In particular context related to the current HTTP\nrequest, e.g. the current logged in user, which is why the recommended\nuse is to pass in the Rack environment.\n\nIf `env` contains a `HTTP_ACCEPT` key (Rack's way of representing the\n`Accept` header), Yaks will return the format that most closely\nmatches what was requested.\n\n\n\n## Namespace\n\nYaks by default will find your mappers for you if they follow the\nnaming convention of appending 'Mapper' to the model class name. This\n(and all other \"conventions\") can be easily redefined though, see the\npolicy section. If you have your mappers inside a\nmodule, use `mapper_namespace`.\n\n```ruby\nmodule API\n module Mappers\n class PostMapper < Yaks::Mapper\n #...\n end\n end\nend\n\nyaks = Yaks.new do\n mapper_namespace API::Mappers\nend\n```\n\nIf your namespace contains a `CollectionMapper`, Yaks will use that\ninstead of `Yaks::CollectionMapper`, e.g.\n\n```ruby\nmodule API\n module Mappers\n class CollectionMapper < Yaks::CollectionMapper\n link :profile, 'http://api.example.com/profiles/collection'\n end\n end\nend\n```\n\nYou can also have collection mappers based on the type of members the\ncollection holds, e.g.\n\n```ruby\nmodule API\n module Mappers\n class LineItemCollectionMapper < Yaks::CollectionMapper\n link :profile, 'http://api.example.com/profiles/line_items'\n attributes :total\n\n def total\n collection.inject(0) do |memo, line_item|\n memo + line_item.price * line_item.quantity\n end\n end\n end\n end\nend\n```\n\nYaks will automatically detect and use this collection when\nserializing an array of `LineItem` objects. See derive_mapper_from_object for\ndetails.\n\n\n## Custom attribute/link/subresource handling\n\nWhen inheriting from `Yaks::Mapper`, you can override\n`map_attributes`, `map_links` and `map_resources` to skip (or augment)\nabove methods, and instead implement your own custom mechanism. These\nmethods take a `Yaks::Resource` instance, and should return an updated\nresource. They should not alter the resource instance in-place. For\nexample\n\n```ruby\nclass ErrorMapper < Yaks::Mapper\n link :profile, '/api/error'\n\n def map_attributes(resource)\n attrs = {\n http_code: 500,\n message: object.to_s,\n type: object.class.name.underscore\n }\n\n case object\n when AllocationException\n attrs[:http_code] = 422\n when ActiveRecord::RecordNotFound\n attrs[:http_code] = 404\n attrs[:type] = \"record_not_found\"\n end\n\n resource.update_attributes(attrs)\n end\nend\n```\n\n## Resources, Formatters, Serializers\n\nYaks uses an intermediate \"Resource\" representation to support\nmultiple output formats. A mapper turns a domain model into a\n`Yaks::Resource`. A formatter (e.g. `Yaks::Format::Hal`) takes\nthe resource and outputs the structure of the target format.\n\nFinally a serializer will take this document structure and turn it\ninto a string. For JSON documents the intermediate format consists of\nRuby primitives like arrays and hashes. HTML/XML based formats on the\nother hand return a [Hexp::Node](https://github.com/plexus/hexp).\n\nFor JSON based format there's an extra step between `format` and\n`serialize` called `primitivize`, this way Ruby objects which don't\nhave an equivalent in the JSON spec, like `Symbol` or `Date`, can be\nturned into objects that are representable in JSON. See\n[Primitiver](#primitivizer).\n\n## Formats\n\nBelow follows a brief overview of formats that are available in\nYaks. The maturity of these formats varies, since we depend on people\nthat use a certain format actively to contribute. Implementing formats\nis in generally straightforward, and consists mostly of deciding how\nthe attributes, links, forms, of a `Yaks::Resource` should be\nrepresented. Depending on the format this might be a subject for\ndebate. We welcome these discussions, and if your opinion differs from\nwhat ends up in Yaks, it should be trivial to change these\nrepresentations for your use case.\n\n### HAL\n\nThis is the default. In HAL one decides when building an API which\nlinks can only be singular (e.g. self), and which are always\nrepresented as an array. Yaks defaults to singular as I've found it to\nbe the most common case. If you want specific links to be plural, then\nconfigure their rel href as such.\n\n```ruby\nhal = Yaks.new do\n format_options :hal, plural_links: ['http://api.example.com/rels/foo']\nend\n```\n\nCURIEs are not explicitly supported (yet), but it's possible to use\nthem with some manual effort.\n\nThe line between a singular resource and a collection is fuzzy in\nHAL. To stick close to the spec you're best to create your own\nsingular types that represent collections, rather than rendering a top\nlevel CollectionResource.\n\nYaks also has a derived format called HALO, which is a non-standard\nextension to HAL which includes form elements.\n\n### HTML\n\nThe hypermedia format *par excellence*. Yaks can generate a version of\nyour API, including links and forms, that is usable straight from a\nstandard web browser. This allows API interactions to be developed and\ntested independent from any client application.\n\nIf you let Yaks handle your content type negotiation (i.e. pass it the\nrack env, and honour the content type it detects, see\n[integration](#integration), simply opening a browser and pointing it\nat your API entry point should do the trick.\n\n### JSON-API\n\n```ruby\nYaks.new do\n default_format :json_api\nend\n```\n\nJSON-API has no concept of outbound links, so these will not be\nrendered. Instead the key will be inferred from the mapper class name\nby default. This can be changed per mapper:\n\n```ruby\nclass AnimalMapper < Yaks::Mapper\n type :pet\nend\n```\n\nOr the policy can be overridden:\n\n```ruby\nyaks = Yaks.new do\n derive_type_from_mapper_class do |mapper_class|\n piglatinize(mapper_class.to_s.sub(/Mapper$/, ''))\n end\nend\n```\n\nFor optional includes, see [`Yaks::Behaviour::OptionalIncludes`](#user-content-behaviours).\n\n### Collection+JSON\n\nCollection+JSON has support for write templates. To use them, the `:template`\noption can be used. It will map the specified form to a CJ template. Please\nnotice that CJ only allows one template per representation.\n\n```ruby\nYaks.new do\n default_format :collection_json\n\n collection_json = Yaks.new do\n format_options :collection_json, template: :my_template_form\n end\nend\n\nclass PostMapper < Yaks::Mapper\n form :my_template_form do\n # This will be used for template\n end\n\n form :not_my_template do\n # This won't be used for template\n end\nend\n```\n\nSubresources aren't mapped because Collection+JSON doesn't really have\nthat concept.\n\n### Transit\n\nThere is experimental support for Transit. The transit gem handles\nserialization internally, so there is no intermediate document. The\n`format` step already returns the serialized string.\n\n## Hooks\n\nIt is possible to hook into the Yaks pipeline to perform extra\nprocessing steps before, after, or around each step. It also possible\nto skip a step.\n\n``` ruby\nyaks = Yaks.new do\n # Automatically give every resource a self link\n after :map, :add_self_link do |resource|\n resource.add_link(Yaks::Resource::Link.new(:self, \"/#{resource.type}/#{resource.attributes[:id]}\"))\n end\n\n # Skip serialization, so Ruby primitives come back instead of JSON\n # This was the default before versions < 0.5.0\n skip :serialize\nend\n```\n\n\n\n## Policy over Configuration\n\nIt's an old adage in the Ruby/Rails world to have \"Convention over Configuration\", mostly to derive values that were not given explicitly. Typically based on things having similar names and a 1-1 derivable relationship.\n\nThis saves a lot of typing, but for the uninitiated it can also create confusion, the implicitness makes it hard to follow what's going on.\n\nWhat's worse, is that often the Configuration part is skipped entirely, making it very hard to deviate from the Golden Standard.\n\nThere is another old adage, \"Policy vs Mechanism\". Implement the mechanisms, but don't dictate the policy.\n\nIn Yaks whenever missing values need to be inferred, like finding an unspecified mapper for a relation, this is handled by a policy object. The default is `Yaks::DefaultPolicy`, you can go there to find all the rules of inference. Single rules of inference can be redefined directly in the Yaks configuration:\n\n```ruby\nyaks = Yaks.new do\n mapper_for Post, SpecialMapper\n\n derive_mapper_from_object do |model|\n # ...\n end\n\n derive_mapper_from_collection do |collection|\n # ...\n end\n\n derive_mapper_from_item do |model|\n # ...\n end\n\n derive_type_from_mapper_class do |mapper_class|\n # ...\n end\n\n derive_mapper_from_association do |association|\n # ...\n end\n\n derive_rel_from_association do |mapper, association|\n # ...\n end\nend\n```\n\nNote that within these blocks, you may call `super()` which would call\nthe default implementation.\n\nYou can also subclass or create from scratch your own policy class\n\n```ruby\nclass MyPolicy < Yaks::DefaultPolicy\n #...\nend\n\nyaks = Yaks.new do\n policy_class MyPolicy\nend\n```\n\n\n\n### derive_mapper_from_object\n\nThis is called when trying to serialize something and no explicit\nmapper is given. To recap, it's always possible to be explicit, e.g.\n\n```\nyaks.call(widget, mapper: WidgetMapper)\nyaks.call(array_of_widgets, mapper: MyCollectionMapper, item_mapper: WidgetMapper)\n```\n\nIf the mapper is left unspecified, Yaks will inspect whatever you pass\nit. First it will test the given object against the mappings defined using `mapper_for`.\nIf no mapper is found, it will call `derive_mapper_from_item` or `derive_mapper_from_collection`\ndepending on whether the given object is a collection or not. If the object responds\nto `to_ary` it is considered a collection.\n\n### mapper_for\n\nThis method allows you to define a one-to-one mapping between a mapping rule and a mapper class.\nDuring the lookup, Yaks will check if any mapping rule matches the given object using the `#===`\noperator.\n\nHere are a few examples on how to use it:\n```ruby\nyaks = Yaks.new do\n mapper_for(:home, HomeMapper)\n mapper_for(Post, SpecialMapper)\n mapper_for(->(author) { author.respond_to?(:name) && author.name == 'doh' }, AuthorMapper)\nend\n\nyaks.call(:home) # would map using HomeMapper\nyaks.call(Post.new) # would map using PostMapper\nyaks.call(Author.new(name: 'doh')) # would map using AuthorMapper\n```\n\n### derive_mapper_from_collection\nThis method will try various constant lookups based on naming. These all happen\nin the configured namespace, which defaults to the Ruby top level.\n\nIf the first object in the collection has a class of `Widget`, and the\nconfigured namespace is `API`, then these are tried in turn\n\n* `API::WidgetCollectionMapper`\n* `API::CollectionMapper`\n* `Yaks::CollectionMapper`\n\nNote that Yaks can only find a specific collection mapper for a type\nif the collection passed to Yaks contains at least one element. If\nit's important that empty collections are handled by the right mapper\n(e.g. to set a specific `self` or `profile` link), then you have to be\nexplicit.\n\n### derive_mapper_from_item\n\nWhen using this method, the lookup happens based on the class name,\nand will traverse up the class hierarchy in the configured namespace if\nno suitable mapper is found. Take the following\ncode:\n```ruby\nmodule Stuff\n class Thing ; end\n class Widget < Thing ; end\nend\n```\nThe lookup we'll be done as followed.\n\n* If the `namespace` option is set (to `Mappers` for example):\n * `Mappers::Stuff::WidgetMapper`\n * `Mappers::Stuff::ThingMapper`\n * `Mappers::Stuff::ObjectMapper`\n * `Mappers::Stuff::BasicObjectMapper`\n * `Mappers::WidgetMapper`\n * `Mappers::ThingMapper`\n\n* If the `namespace` option is not set:\n * `Stuff::WidgetMapper`\n * `Stuff::ThingMapper`\n * `Stuff::ObjectMapper`\n * `Stuff::BasicObjectMapper`\n * `WidgetMapper`\n * `ThingMapper`\n\nIf none of these are found an error is raised.\n\n### derive_mapper_from_association\n\nWhen no mapper is specified for an association, then this method is\ncalled to find the right mapper, based on the association name. In\ncase of `has_many` collections this is the \"item mapper\", the\ncollection mapper is resolved using `derive_mapper_from_object`.\n\nBy default the mapper class is derived from the name of the association, e.g.\n\n```\nhas_many :widgets #=> WidgetMapper\nhas_one :widget #=> WidgetMapper\n```\n\nIt is always possible to explicitly set a mapper.\n\n```\nhas_one :widget, mapper: FooMapper\nhas_many :widgets, collection_mapper: MyCollectionMapper, mapper: FooMapper\n```\n\n### derive_rel_from_association\n\nAssociations have a \"rel\", an IANA registered identifier or fully\nqualified URI, that specifies how the object relates to the parent\ndocument.\n\nWhen configuring Yaks one can set a `rel_template`, that will be used\nto generate these rels if not explicitly given. The `rel` placeholder\nin the template will be substituted with the association name.\n\n``` ruby\nyaks = Yaks.new do\n rel_template \"http://api.example.com/rel/{rel}\"\nend\n\nclass MyMapper < Yaks::Mapper\n # rel: \"http://api.example.com/rel/widgets\"\n has_many :widgets\n\n # rel: \"http://api.example.com/rel/widget\"\n has_one :widget\nend\n```\n\n\n\n## Primitivizer\n\nFor JSON based formats, the \"syntax tree\" is merely a structure of Ruby primitives that have a JSON equivalent. If your mappers return non-primitive attribute values, you can define how they should be converted. For example, JSON has no notion of dates. If your mappers return these types as attributes, then Yaks needs to know how to turn these into primitives. To add extra types, use `map_to_primitive`\n\nHere's an example with a custom `Currency` class, which can be represented as an integer.\n\n```ruby\nYaks.new do\n map_to_primitive Currency do |currency|\n currency.to_i\n end\nend\n```\n\nOne notable use case is representing dates and times. The JSON\nspecification does not define any syntax for these, so the only\nsolution is to represent them either as numbers or strings. If you're\nnot sure what to do with these then the ISO8601 standard is a safe\nbet. It defines a way to represent times and dates as strings, and is\nalso adopted by the W3C in [RFC3339](http://tools.ietf.org/html/rfc3339).\n\nAn alternative representation that is sometimes used is \"unix time\",\ndefined as the numbers of seconds passed since 1 January 1970.\n\nHere's an example for a Rails app, so including ActiveSupport's `TimeWithZone`.\n\n```ruby\nYaks.new do\n map_to_primitive Date, Time, DateTime, ActiveSupport::TimeWithZone, &:iso8601\nend\n```\n\n`map_to_primitive` can also be used to transform alternative data\nstructures, like those from [Hamster](https://github.com/hamstergem/hamster),\ninto Ruby arrays and hashes. Use `call()` to recursively turn things into\nprimitives.\n\n```ruby\nYaks.new do\n map_to_primitive Hamster::Vector, Hamster::List do |list|\n list.map do |item|\n call(item)\n end\n end\nend\n```\n\nYaks by default \"primitivizes\" symbols (as strings), and classes that include Enumerable (as arrays).\n\n\n\n\n## Integration\n\nIt is recommended to let Yaks handle the negotiation of media types,\nso that consumer can request the format they prefer using an `Accept:`\nheader. To do this requires two steps: first make sure you pass the\nrack env to Yaks, this way it will detect any `Accept` header and\nhonor it. While this is enough to get the correct serialized output,\nit will likely be served up with the wrong `Content-Type` header by\nyour web framework.\n\nTo fix this, ask Yaks first for the \"runner\" for a given input, then\nget the media type and serialized resource from the runner.\n\n```ruby\n# Tell your web framework about the supported formats\nYaks::Format.all.each do |format|\n mime_type format.format_name, format.media_type\nend\n\n# one time Yaks configuration\nyaks = Yaks.new\n\n# on each request\nrunner = yaks.runner(post, env: rack_env)\nformat = runner.format_name\noutput = runner.call\n```\n\n\n## Real World Usage\n\nYaks is used in production by\n\n* [Ticketsolve](http://www.ticketsolve.com/). You can find an example API endpoint [here](http://leicestersquaretheatre.ticketsolve.com/api).\n* Advertile Mobile for their product AppBounty (internal API)\n\n## Demo\n\nYou can find an outdated example app at [Yakports](https://github.com/plexus/yakports), or browse the HAL api directly using the [HAL browser](http://yaks-airports.herokuapp.com/browser.html).\n\n## Cookbook\n\nSee the [cookbook](COOKBOOK.md) for some usage examples taking from a real world app.\n\n## Standards Based\n\nYaks is based on internet standards, including\n\n* [RFC4288 Media types](http://tools.ietf.org/html/rfc4288)\n* [RFC5988 Web Linking](http://tools.ietf.org/html/rfc5988)\n* [RFC6906 The \"profile\" link relation](http://tools.ietf.org/search/rfc6906)\n* [RFC6570 URI Templates](http://tools.ietf.org/html/rfc6570)\n* [RFC4229 HTTP Header Field Registrations](http://tools.ietf.org/html/rfc4229).\n\n## How to contribute\n\nRun the tests, the examples, try it with your own stuff and leave your impressions in the issues.\n\nTo fix a bug\n\n1. Fork the repo\n2. Fix the bug, add tests for it\n3. Push it to a named branch\n4. Add a PR\n\nTo add a feature\n\n1. Open an issue as soon as possible to gather feedback\n2. Same as above, fork, push to named branch, make a pull-request\n\nYaks uses [Mutation Testing](https://github.com/mbj/mutant). Run `rake mutant` and look for percentage coverage. In general this should only go up.\n\n## License\n\nMIT License (Expat License), see [LICENSE](./LICENSE)\n\n![](shaved_yak.gif)\n" }, { "path": "yaks/Rakefile", "content": "load '../shared/rake_tasks.rb'\n\ngem_tasks(:yaks)\n\ntask :mutant_chunked do\n # No subjects:\n # Yaks,\n # Yaks::Error,\n # Yaks::IllegalStateError,\n # Yaks::UnsupportedOperationError,\n # Yaks::PrimitivizeError,\n # Yaks::Undefined,\n # Yaks::HTML5Forms,\n\n # Hangs:\n # Yaks::Changelog,\n\n # 100% verified:\n # Yaks::Util,\n # Yaks::Util::Deprecated,\n # Yaks::FP\n # Yaks::FP::Callable,\n # Yaks::DefaultPolicy,\n # Yaks::Mapper::HasOne,\n # Yaks::Mapper::HasMany,\n # Yaks::Mapper::Attribute,\n # Yaks::Mapper::Config,\n # Yaks::Mapper::ClassMethods,\n # Yaks::Mapper::AssociationMapper,\n # Yaks::Format::CollectionJson,\n # Yaks::Config,\n # Yaks::Config::DSL,\n # Yaks::Attributes::InstanceMethods,\n # Yaks::Configurable,\n # Yaks::NullResource,\n # Yaks::Runner,\n\n [\n # >> Yaks::Attributes\n # >> Yaks::Attributes::InstanceMethods\n # >> Yaks::Builder\n # >> Yaks::CollectionMapper\n # >> Yaks::CollectionResource\n # >> Yaks::Config\n # >> Yaks::Configurable\n # >> Yaks::DefaultPolicy\n # >> Yaks::Error\n # >> Yaks::FP\n # >> Yaks::FP::Callable\n # >> Yaks::Format\n # >> Yaks::Format::CollectionJson\n # >> Yaks::Format::HTML\n # >> Yaks::Format::Hal\n # >> Yaks::Format::Halo\n # >> Yaks::Format::JsonAPI\n # >> Yaks::Format::Reader\n # >> Yaks::Format::Transit\n # >> Yaks::Format::Transit::ReadHandler\n # >> Yaks::Format::Transit::WriteHandler\n # >> Yaks::HTML5Forms\n # >> Yaks::IllegalStateError\n # >> Yaks::Mapper\n # >> Yaks::Mapper::Association\n # >> Yaks::Mapper::AssociationMapper\n # >> Yaks::Mapper::Attribute\n # >> Yaks::Mapper::Config\n # >> Yaks::Mapper::Form\n # >> Yaks::Mapper::Form::Config\n # >> Yaks::Mapper::Form::Field\n # >> Yaks::Mapper::Form::Field::Option\n # >> Yaks::Mapper::Form::Fieldset\n # >> Yaks::Mapper::HasMany\n # >> Yaks::Mapper::HasOne\n # >> Yaks::Mapper::Link\n # >> Yaks::NullResource\n # >> Yaks::Pipeline\n # >> Yaks::Primitivize\n # >> Yaks::PrimitivizeError\n # >> Yaks::Reader\n # >> Yaks::Reader::Hal\n # Yaks::Resource,\n # Yaks::Resource::Form,\n # Yaks::Resource::Form::Field,\n # Yaks::Resource::Form::Field::Option,\n # Yaks::Resource::Form::Fieldset,\n # Yaks::Resource::Link,\n Yaks::Resource::HasFields,\n # >> Yaks::Runner\n # >> Yaks::RuntimeError\n # >> Yaks::Serializer\n # >> Yaks::Serializer::JSONReader\n # >> Yaks::Serializer::JSONWriter\n # >> Yaks::Undefined\n # >> Yaks::UnsupportedOperationError\n # >> Yaks::Util\n # >> Yaks::Util::Deprecated\n ].each do |space|\n puts space\n ENV['PATTERN'] = \"#{space}\"\n Rake::Task[\"mutant\"].execute\n break\n end\nend\n" }, { "path": "yaks/ataru_setup.rb", "content": "# \"Require your project source code, with the correct path\"\n\nrequire \"yaks\"\nrequire \"hamster\"\n\nPost = Struct.new(:id, :title, :author, :comments)\nAuthor = Struct.new(:name)\n\nmodule MyAPI\n Product = Struct.new(:id, :label)\n\n class ProductMapper < Yaks::Mapper\n attributes :id, :label\n end\nend\n\nclass AuthorMapper < Yaks::Mapper\nend\n\nclass CommentMapper < Yaks::Mapper\nend\n\nclass PostMapper < Yaks::Mapper\n link :self, '/api/posts/{id}'\n\n attributes :id, :title\n\n has_one :author\n has_many :comments\nend\n\nclass HomeMapper < Yaks::Mapper; end\n\nclass SpecialMapper < Yaks::Mapper; end\n\nmodule ActiveSupport\n class TimeWithZone < Time ; end\nend\n\nclass Currency ; end\n\nmodule Setup\n def setup\n # Do some nice setup that is run before every snippet\n # If you'd like to use instance variables define them here, e.g\n # @important_variable_i_will_use_in_my_code_snippets = true\n end\n\n def teardown\n # Do some cleanup that is run after every snippet\n end\n\n # If you like local variables you can define methods, e.g\n # def number_of_wishes\n # 101\n # end\n\n def my_env\n {'something' => true}\n end\n alias_method :rack_env, :my_env\n\n def post\n Post.new(7, \"Yaks is Al Dente\", nil, [])\n end\n alias_method :foo, :post\n\n def product\n MyAPI::Product.new(42, \"Shiny thing\")\n end\n\n # # Tell your web framework about the supported formats\n # Yaks::Format.all.each do |format|\n # mime_type format.format_name, format.media_type\n # end\n def mime_type(*_args)\n end\nend\n" }, { "path": "yaks/find_missing_tests.rb", "content": "#!/usr/bin/env ruby\n\nrequire 'mutant'\nrequire 'pry'\n\n# These are private methods that are tested by other methods in the same class\nSKIP = %w[\n Yaks::CollectionMapper#collection_rel\n Yaks::CollectionMapper#collection_type\n Yaks::CollectionMapper#mapper_for_model\n Yaks::Resource::Form::Field#select_options_for_value\n Yaks::Mapper::AssociationMapper#add_link\n Yaks::Mapper::AssociationMapper#add_subresource\n Yaks::Mapper::Link#resource_link_options\n]\n\nargs = [\"-Ilib\", \"-ryaks\", \"--use\", \"rspec\", \"Yaks*\"]\nenv = Mutant::Env::Bootstrap.call(Mutant::CLI.call(args))\n\nintegration = env.config.integration\n\nintegration.setup\nbinding.pry if integration.all_tests.empty? # rubocop:disable Lint/Debugger\n\nenv.subjects.each do |subject|\n match_expression = subject.match_expressions.first\n subject_tests = integration.all_tests.select do |test|\n match_expression.prefix?(test.expression)\n end\n unless subject_tests.any? || SKIP.include?(subject.expression.syntax)\n puts subject.identification\n exit if ARGV.include?(\"-1\")\n end\nend\n" }, { "path": "yaks/lib/yaks/behaviour/optional_includes.rb", "content": "require \"rack/utils\"\n\nmodule Yaks\n module Behaviour\n module OptionalIncludes\n RACK_KEY = \"yaks.optional_includes\".freeze\n\n def associations\n super.select do |association|\n association.if != Undefined || include_association?(association)\n end\n end\n\n private\n\n def include_association?(association)\n includes = env.fetch(RACK_KEY) do\n query_string = env.fetch(\"QUERY_STRING\", nil)\n query = Rack::Utils.parse_query(query_string)\n env[RACK_KEY] = query.fetch(\"include\", \"\").split(\",\").map { |r| r.split(\".\") }\n end\n\n includes.any? do |relationship|\n relationship[mapper_stack.size].eql?(association.name.to_s)\n end\n end\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/breaking_changes.rb", "content": "module Yaks\n# These are displayed in a post-install message when installing the\n# gem to aid upgraiding\n\nBreakingChanges = {\n\n '0.7.6' => %q~\nBreaking Changes in Yaks 0.7.6\n==============================\nBreaking change: using a symbol instead of link template no longer\nworks, use a lambda.\n\n link :foo, :bar\n\nBecomes\n\n link :foo, ->{ bar }\n\nStrictly speaking the equivalent version would be `link :foo, ->{\nload_attribute(:bar) }`. Depending on if `bar` is implemented on the\nmapper or is an attribute of the object, this would simplify to `link\n:foo, ->{ bar }` or `link :foo, ->{ object.bar }` respectively.\n\nThe `href` attribute of a control has been renamed `action`, in line\nwith the attribute name in HTML. An alias is available but will output\na deprecation warning.\n~,\n\n '0.7.0' => %q~\nBreaking Changes in Yaks 0.7.0\n==============================\nYaks::Resource#subresources is now an array, not a hash. The rel is\nstored on the resource itself as Yaks::Resource#rels (an array). This\nshould only be of concern if you implement custom output formats\n\nThe general signature of all processing steps (mapper, formatter,\nhooks) has changed to incldue a second parameter, the rack env. If you\nhave custom implementations of any of these, or hooks that are not\nspecified as ruby blocks, you will need to take this into account\n~,\n\n '0.5.0' => %q~\n\nBreaking Changes in Yaks 0.5.0\n==============================\n\nYaks now serializes its output, you no longer have to convert to JSON\nyourself. Use `skip :serialize' to get the old behavior, or\n`json_serializer` to use a different JSON implementation.\n\nThe single `after' hook has been replaced with a set of `before',\n`after', `around' and `skip' hooks.\n\nIf you've created your own subclass of `Yaks::Format' (previously:\n`Yaks::Serializer'), then you need to update the call to\n`Format.register'.\n\nThese are potentially breaking changes. See the CHANGELOG and README\nfor full documentation.\n\n~,\n\n '0.4.3' => %q~\n\nBreaking Changes in Yaks 0.4.3\n==============================\n\nYaks::Mapper#filter was removed, if you override this method in your\nmappers to conditionally filter attributes or associations, you will\nhave to override #attributes or #associations instead.\n\nWhen specifying a rel_template, now a single {rel} placeholder is\nexpected instead of {src} and {dest}.\n\nThere are other internal changes. See the CHANGELOG and README for full\ndocumentation.\n\n~\n}\n\nBreakingChanges['0.4.4'] = BreakingChanges['0.4.3']\nBreakingChanges['0.7.1'] = BreakingChanges['0.7.0']\nend\n" }, { "path": "yaks/lib/yaks/builder.rb", "content": "module Yaks\n # State monad-ish thing.\n #\n # Generate a DSL syntax for immutable classes.\n #\n # @example\n #\n # # This code\n # Form.create(:search)\n # .method(\"POST\")\n # .action(\"/search\")\n #\n # # Can be written as\n # Builder.new(Form, [:method, :action]).create(:search) do\n # method \"POST\"\n # action \"/search\"\n # end\n #\n class Builder\n include Configurable\n\n def initialize(klass, methods = [], &block)\n @klass = klass\n @methods = methods\n def_forward(*methods) if methods.any?\n instance_eval(&block) if block\n end\n\n def create(*args, &block)\n build(@klass.create(*args), &block)\n end\n\n def build(init_state, *extra_args, &block)\n @config = init_state\n instance_exec(*extra_args, &block) if block\n @config\n end\n\n def inspect\n \"#\"\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/changelog.rb", "content": "module Yaks\n module Changelog\n module_function\n\n def current\n versions[Yaks::VERSION]\n end\n\n def versions\n markdown.split(/(?=###\\s*[\\d\\w\\.]+\\n)/).each_with_object({}) do |section, hsh|\n version = section.each_line.first[/[\\d\\w\\.]+/]\n log = section.each_line.drop(1).join.strip\n hsh[version] = log\n end\n end\n\n def markdown\n Pathname(__FILE__).join('../../../../CHANGELOG.md').read\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/collection_mapper.rb", "content": "module Yaks\n class CollectionMapper < Mapper\n alias_method :collection, :object\n\n # @param [Array] collection\n # @return [Array]\n def call(collection, _env = nil)\n @object = collection\n\n attrs = {\n type: collection_type,\n members: collection().map do |obj|\n mapper_for_model(obj).new(context).call(obj)\n end\n }\n\n # For collections from associations the rel will be based on the\n # association. At the top level there's no association, so we\n # use a generic rel. This matters especially for HAL, where a\n # top-level collection is rendered as an object with the\n # collection as a subresource.\n attrs[:rels] = [collection_rel] if context[:mapper_stack].empty?\n\n map_attributes(\n map_links(\n CollectionResource.new(attrs)\n )\n )\n end\n\n private\n\n def collection_rel\n if collection_type\n policy.expand_rel(pluralize(collection_type))\n else\n 'collection'\n end\n end\n\n def collection_type\n if item_mapper = context[:item_mapper]\n item_mapper.config.type || policy.derive_type_from_mapper_class(item_mapper)\n else\n policy.derive_type_from_collection(collection)\n end\n end\n\n def mapper_for_model(model)\n context.fetch(:item_mapper) do\n policy.derive_mapper_from_object(model)\n end\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/collection_resource.rb", "content": "module Yaks\n # A collection of Resource objects, it has members, and its own set of link\n # relations like self and profile describing the collection.\n #\n # A collection can be the top-level result of an API call, like all posts to\n # a blog, or a subresource collection, like the comments on a post result.\n #\n class CollectionResource < Resource\n include attributes.add(members: [])\n\n extend Forwardable\n def_delegators :members, :each, :map, :each_with_object\n\n # @return [Boolean]\n def collection?\n true\n end\n\n def seq\n self\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/config.rb", "content": "module Yaks\n class Config\n extend Yaks::Util::Deprecated\n include Yaks::FP::Callable,\n Attribs.new(\n format_options_hash: Hash.new({}),\n default_format: :hal,\n policy_options: {},\n policy_class: DefaultPolicy,\n primitivize: Primitivize.create,\n serializers: Serializer.all,\n hooks: []\n )\n\n class << self\n alias_method :create, :new\n end\n\n deprecated_alias :namespace, :mapper_namespace\n\n def format_options(format, options)\n with(format_options_hash: format_options_hash.merge(format => options))\n end\n\n def serializer(type, &serializer)\n with(serializers: serializers.merge(type => serializer))\n end\n\n def json_serializer(&serializer)\n serializer(:json, &serializer)\n end\n\n %w[before after around skip].map(&:intern).each do |hook_type|\n define_method hook_type do |step, name = :\"#{hook_type}_#{step}\", &block|\n append_to(:hooks, [hook_type, step, name, block])\n end\n end\n\n def rel_template(template)\n with(policy_options: policy_options.merge(rel_template: template))\n end\n\n def mapper_namespace(namespace)\n with(policy_options: policy_options.merge(namespace: namespace))\n end\n\n def mapper_for(rule, mapper_class)\n policy_options[:mapper_rules] ||= {}\n mapper_rules = policy_options[:mapper_rules].merge(rule => mapper_class)\n with(policy_options: policy_options.merge(mapper_rules: mapper_rules))\n end\n\n def map_to_primitive(*args, &block)\n with(primitivize: primitivize.dup.tap { |prim| prim.map(*args, &block) })\n end\n\n DefaultPolicy.public_instance_methods(false).each do |method|\n define_method method do |&block|\n with(\n policy_class: Class.new(policy_class) do\n define_method method, &block\n end\n )\n end\n end\n\n # @return [Yaks::DefaultPolicy]\n def policy\n @policy ||= @policy_class.new(@policy_options)\n end\n\n def runner(object, options)\n Runner.new(config: self, object: object, options: options)\n end\n\n # Main entry point into yaks\n #\n # @param object [Object] The object to serialize\n # @param options [Hash] Serialization options\n #\n # @option env [Hash] The rack environment\n # @option format [Symbol] The target format, default :hal\n # @option mapper [Class] Mapper class to use\n # @option item_mapper [Class] Mapper class to use for items in a top-level collection\n #\n def call(object, options = {})\n runner(object, options).call\n end\n alias_method :serialize, :call\n\n def map(object, options = {})\n runner(object, options).map\n end\n\n def format(data, options = {})\n runner(data, options).format\n end\n\n def read(data, options = {})\n runner(data, options).read\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/configurable.rb", "content": "module Yaks\n # A \"Configurable\" class is one that keeps a configuration in a\n # separate immutable object, of type class::Config. say you have\n #\n # class MyMapper < Yaks::Mapper\n # # use yaks configuration DSL in here\n # end\n #\n # The links, associations, etc, that you set up for MyMapper, will\n # be available in MyMapper.config, which is an instance of\n # Yaks::Mapper::Config.\n #\n # Each configuration step, like `link`, `has_many`, will replace\n # MyMapper.config with an updated version, discarding the old\n # config.\n #\n # By extending Configurable, a number of \"macros\" become available\n # to describe the DSL that subclasses can use. See the docs for\n # `def_set`. `def_forward`, and `def_add`.\n module Configurable\n attr_accessor :config\n\n def self.extended(child)\n child.config = child::Config.new\n end\n\n def inherited(child)\n child.config = config\n end\n\n # Create a DSL method to set a certain config property. The\n # generated method will take either a plain value, or a block,\n # which will be captured and stored instead.\n def def_set(*method_names)\n method_names.each do |method_name|\n define_singleton_method method_name do |arg = Undefined, &block|\n if arg.equal?(Undefined)\n unless block\n raise ArgumentError, \"setting #{method_name}: no value and no block given\"\n end\n self.config = config.with(method_name => block)\n else\n if block\n raise ArgumentError, \"ambiguous invocation setting #{method_name}: give either a value or a block, not both.\"\n end\n self.config = config.with(method_name => arg)\n end\n end\n end\n end\n\n # Forward a method to the config object. This assumes the method\n # will return an updated config instance.\n #\n # Either takes a list of methods to forward, or a mapping (hash)\n # of source to destination method name.\n def def_forward(mappings, *names)\n if mappings.instance_of? Hash\n mappings.each do |method_name, target|\n define_singleton_method method_name do |*args, &block|\n self.config = config.public_send(target, *args, &block)\n end\n end\n else\n def_forward([mappings, *names].map{|name| {name => name}}.inject(:merge))\n end\n end\n\n # Generate a DSL method that creates a certain type of domain\n # object, and adds it to a list on the config.\n #\n # def_add :fieldset, create: Fieldset, append_to: :fields\n #\n # This will generate a `fieldset` method, which will call\n # `Fieldset.create`, and append the result to `config.fields`\n def def_add(name, options)\n old_verbose, $VERBOSE = $VERBOSE, false # skip method redefinition warning\n define_singleton_method name do |*args, &block|\n defaults = options.fetch(:defaults, {})\n klass = options.fetch(:create)\n\n if args.last.instance_of?(Hash)\n args[-1] = defaults.merge(args[-1])\n else\n args << defaults\n end\n\n self.config = config.append_to(\n options.fetch(:append_to),\n klass.create(*args, &block)\n )\n end\n ensure\n $VERBOSE = old_verbose\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/default_policy.rb", "content": "\nmodule Yaks\n class DefaultPolicy\n include Util\n\n # Default policy options.\n DEFAULTS = {\n rel_template: \"rel:{rel}\",\n namespace: Object,\n mapper_rules: {}\n }\n\n # @!attribute [r]\n # @return [Hash]\n attr_reader :options\n\n # @param options [Hash] options\n def initialize(options = {})\n @options = DEFAULTS.merge(options)\n end\n\n # Main point of entry for mapper derivation. Calls\n # derive_mapper_from_collection or derive_mapper_from_item\n # depending on the model.\n #\n # @param model [Object]\n # @return [Class] A mapper, typically a subclass of Yaks::Mapper\n #\n # @raise [RuntimeError] occurs when no mapper is found\n def derive_mapper_from_object(model)\n mapper = detect_configured_mapper_for(model)\n return mapper if mapper\n return derive_mapper_from_collection(model) if model.respond_to? :to_ary\n derive_mapper_from_item(model)\n end\n\n # Derives a mapper from the given collection.\n #\n # @param collection [Object]\n # @return [Class] A mapper, typically a subclass of Yaks::Mapper\n def derive_mapper_from_collection(collection)\n if m = collection.first\n name = \"#{m.class.name.split('::').last}CollectionMapper\"\n begin\n return @options[:namespace].const_get(name)\n rescue NameError # rubocop:disable Lint/HandleExceptions\n end\n end\n begin\n return @options[:namespace].const_get(:CollectionMapper)\n rescue NameError # rubocop:disable Lint/HandleExceptions\n end\n CollectionMapper\n end\n\n # Derives a mapper from the given item. This item should not\n # be a collection.\n #\n # @param item [Object]\n # @return [Class] A mapper, typically a subclass of Yaks::Mapper\n #\n # @raise [RuntimeError] only occurs when no mapper is found for the given item.\n def derive_mapper_from_item(item)\n klass = item.class\n namespaces = klass.name.split(\"::\")[0...-1]\n begin\n return build_mapper_class(namespaces, klass)\n rescue NameError\n klass = next_class_for_lookup(item, namespaces, klass)\n retry if klass\n end\n raise_mapper_not_found(item)\n end\n\n # Derive the a mapper type name\n #\n # This returns the 'system name' for a mapper,\n # e.g. ShowEventMapper => show_event.\n #\n # @param [Class] mapper_class\n #\n # @return [String]\n def derive_type_from_mapper_class(mapper_class)\n underscore(mapper_class.name.split('::').last.sub(/Mapper$/, ''))\n end\n\n # Derive the mapper type name from a collection\n #\n # This inspects the first element of the collection, so\n # it requires a collection with truthy elements. Will\n # return `nil` if the collection has no truthy elements.\n #\n # @param [#first] collection\n #\n # @return [String|nil]\n #\n # @raise [NameError]\n def derive_type_from_collection(collection)\n return if collection.none?\n derive_type_from_mapper_class(derive_mapper_from_object(collection.first))\n end\n\n def derive_mapper_from_association(association)\n @options[:namespace].const_get(\"#{camelize(association.singular_name)}Mapper\")\n end\n\n # @param association [Yaks::Mapper::Association]\n # @return [String]\n def derive_rel_from_association(association)\n expand_rel(association.name)\n end\n\n # @param relname [String]\n # @return [String]\n def expand_rel(relname)\n URITemplate.new(@options[:rel_template]).expand(rel: relname)\n end\n\n private\n\n def build_mapper_class(namespaces, klass)\n mapper_class = \"#{klass.name.split('::').last}Mapper\"\n [*namespaces, mapper_class].inject(@options[:namespace]) do |namespace, module_or_class|\n namespace.const_get(module_or_class, false)\n end\n end\n\n def next_class_for_lookup(item, namespaces, klass)\n superclass = klass.superclass\n return superclass if superclass < Object\n return nil if namespaces.empty?\n namespaces.clear\n item.class\n end\n\n def raise_mapper_not_found(item)\n namespace = \"#{@options[:namespace]}::\" unless Object.equal?(@options[:namespace])\n mapper_class = \"#{namespace}#{item.class}Mapper\"\n raise \"Failed to find a mapper for #{item.inspect}. Did you mean to implement #{mapper_class}?\"\n end\n\n def detect_configured_mapper_for(object)\n @options[:mapper_rules].each do |rule, mapper_class|\n return mapper_class if rule === object # rubocop:disable Style/CaseEquality\n end\n nil\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/errors.rb", "content": "module Yaks\n Error = Class.new(StandardError)\n\n IllegalStateError = Class.new(Error)\n RuntimeError = Class.new(Error)\n UnsupportedOperationError = Class.new(Error)\n PrimitivizeError = Class.new(Error)\nend\n" }, { "path": "yaks/lib/yaks/format/collection_json.rb", "content": "module Yaks\n class Format\n class CollectionJson < self\n register :collection_json, :json, 'application/vnd.collection+json'\n\n include FP\n\n # @param [Yaks::Resource] resource\n # @return [Hash]\n def serialize_resource(resource)\n result = {\n version: \"1.0\",\n items: serialize_items(resource)\n }\n result[:href] = resource.self_link.uri if resource.self_link\n result[:links] = serialize_links(resource) if links?(resource)\n result[:queries] = serialize_queries(resource) if queries?(resource)\n result[:template] = serialize_template(resource) if template?(resource)\n {collection: result}\n end\n\n # @param [Yaks::Resource] resource\n # @return [Array]\n def serialize_items(resource)\n resource.seq.map do |item|\n attrs = item.attributes.map do |name, value|\n {\n name: name,\n value: value\n }\n end\n result = {data: attrs}\n result[:href] = item.self_link.uri if item.self_link\n item.links.each do |link|\n next if link.rel.equal? :self\n result[:links] = [] unless result.key?(:links)\n result[:links] << {rel: link.rel, href: link.uri}\n result[:links].last[:name] = link.title if link.title\n end\n result\n end\n end\n\n def serialize_links(resource)\n resource.links.each_with_object([]) do |link, result|\n result << {href: link.uri, rel: link.rel}\n end\n end\n\n def serialize_queries(resource)\n resource.forms.each_with_object([]) do |form, result|\n next unless form_is_query? form\n\n result << {rel: form.name, href: form.action}\n result.last[:prompt] = form.title if form.title\n\n form.fields_flat.each do |field|\n result.last[:data] = [] unless result.last.key? :data\n result.last[:data] << {name: field.name, value: nil.to_s}\n result.last[:data].last[:prompt] = field.label if field.label\n end\n end\n end\n\n def queries?(resource)\n resource.forms.any? { |f| form_is_query? f }\n end\n\n def links?(resource)\n resource.collection? && resource.links.any?\n end\n\n def template?(resource)\n options.key?(:template) && template_form_exists?(resource)\n end\n\n protected\n\n def form_is_query?(form)\n form.method?(:get) && form.has_action?\n end\n\n def template_form_exists?(resource)\n !resource.find_form(options.fetch(:template)).nil?\n end\n\n def serialize_template(resource)\n fields = resource.find_form(options.fetch(:template)).fields\n result = {data: []}\n fields.each do |field|\n result[:data] << {name: field.name, value: nil.to_s}\n result[:data].last[:prompt] = field.label if field.label\n end\n result\n end\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/format/hal.rb", "content": "module Yaks\n class Format\n # Hypertext Application Language (http://stateless.co/hal_specification.html)\n #\n # A lightweight JSON Hypermedia message format.\n #\n # Options: +:plural_links+ In HAL, a single rel can correspond to\n # a single link, or to a list of links. Which rels are singular\n # and which are plural is application-dependant. Yaks assumes all\n # links are singular. If your resource might contain multiple\n # links for the same rel, then configure that rel to be plural. In\n # that case it will always be rendered as a collection, even when\n # the resource only contains a single link.\n #\n # @example\n #\n # yaks = Yaks.new do\n # format_options :hal, {plural_links: [:related_content]}\n # end\n #\n class Hal < self\n register :hal, :json, 'application/hal+json'\n\n def transitive?\n true\n end\n\n def inverse\n Yaks::Reader::Hal.new\n end\n\n protected\n\n # @param [Yaks::Resource] resource\n # @return [Hash]\n def serialize_resource(resource)\n # The HAL spec doesn't say explicitly how to deal missing values,\n # looking at client behavior (Hyperagent) it seems safer to return an empty\n # resource.\n #\n result = resource.attributes\n\n if resource.links.any?\n result = result.merge(_links: serialize_links(resource.links))\n end\n\n if resource.collection?\n result = result.merge(_embedded:\n serialize_embedded([resource]))\n elsif resource.subresources.any?\n result = result.merge(_embedded:\n serialize_embedded(resource.subresources))\n end\n\n result\n end\n\n # @param [Array] links\n # @return [Hash]\n def serialize_links(links)\n links.reduce({}, &method(:serialize_link))\n end\n\n # @param [Hash] memo\n # @param [Yaks::Resource::Link]\n # @return [Hash]\n def serialize_link(memo, link)\n hal_link = {href: link.uri}\n hal_link.merge!(link.options)\n\n memo[link.rel] = if singular?(link.rel)\n hal_link\n else\n (memo[link.rel] || []) + [hal_link]\n end\n memo\n end\n\n # @param [String] rel\n # @return [Boolean]\n def singular?(rel)\n !options.fetch(:plural_links) { [] }.include?(rel)\n end\n\n # @param [Array] subresources\n # @return [Hash]\n def serialize_embedded(subresources)\n subresources.each_with_object({}) do |sub, memo|\n memo[sub.rels.first] = if sub.collection?\n sub.map(&method(:serialize_resource))\n elsif sub.null_resource?\n nil\n else\n serialize_resource(sub)\n end\n end\n end\n end\n end\nend\n" }, { "path": "yaks/lib/yaks/format/halo.rb", "content": "module Yaks\n class Format\n # Extension of Hal loosely based on the example by Mike Kelly given at\n # https://gist.github.com/mikekelly/893552\n class Halo < Hal\n register :halo, :json, 'application/halo+json'\n\n def serialize_resource(resource)\n if resource.forms.any?\n super.merge(_controls: serialize_forms(resource.forms))\n else\n super\n end\n end\n\n def serialize_forms(forms)\n forms.each_with_object({}) do |form, result|\n result[form.name] = serialize_form(form)\n end\n end\n\n def serialize_form(form)\n raw = form.to_h_compact\n raw[:href] = raw.delete(:action) if raw[:action]\n raw[:fields] = form.fields.map(&method(:serialize_form_field))\n raw\n end\n\n def serialize_form_field(field)\n if field.type == :fieldset\n {\n type: :fieldset,\n fields: field.fields.map(&method(:serialize_form_field))\n }\n else\n field.to_h_compact.each_with_object({}) do |(attr, value), hsh|\n if attr == :options #