{"id":18271647,"url":"https://github.com/karelia/KSHTMLWriter","last_synced_at":"2025-04-05T02:30:37.144Z","repository":{"id":75822755,"uuid":"778625","full_name":"karelia/KSHTMLWriter","owner":"karelia","description":"Small set of classes to simplify XML/HTML generation in Cocoa apps.","archived":false,"fork":false,"pushed_at":"2018-09-25T05:12:58.000Z","size":848,"stargazers_count":77,"open_issues_count":0,"forks_count":13,"subscribers_count":7,"default_branch":"v2.x-beta","last_synced_at":"2024-11-05T11:54:02.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karelia.png","metadata":{"files":{"readme":"README.mdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-07-16T10:47:43.000Z","updated_at":"2023-06-15T16:23:01.000Z","dependencies_parsed_at":"2023-03-11T20:31:07.060Z","dependency_job_id":null,"html_url":"https://github.com/karelia/KSHTMLWriter","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karelia%2FKSHTMLWriter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karelia%2FKSHTMLWriter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karelia%2FKSHTMLWriter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karelia%2FKSHTMLWriter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karelia","download_url":"https://codeload.github.com/karelia/KSHTMLWriter/tar.gz/refs/heads/v2.x-beta","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247279224,"owners_count":20912848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T11:39:26.039Z","updated_at":"2025-04-05T02:30:37.077Z","avatar_url":"https://github.com/karelia.png","language":"Objective-C","readme":"KSHTMLWriter\n=============\n\nKSHTMLWriter is a set of classes for generating HTML and XML markup programmatically. It is quite easy in Cocoa to start producing XML by using `+stringWithFormat:` etc. but this can quickly grow to become unwieldy. KSHTMLWriter simplifies the task considerably, while offering plenty of flexibility.\n\nAnother benefit is that markup is generated in a stream-like fashion, potentially cutting down on memory overhead. You can think of it as the opposite of `NSXMLParser` etc.\n\n`KSHTMLWriter` instances are safe to use on any thread, but should only be accessed by a single thread at a time.\n\nAdding KSHTMLWriter to your project\n====================================\n\n### Cross-Platform ###\n\nThe simplest way to add KSHTMLWriter to your project is to directly add the source files to your project. For XML generation, the following are required:\n\n- KSWriter/*\n- KSXMLWriter.h\n- KSXMLWriter.m\n- KSElementInfo.h\n- KSElementInfo.m\n\nFor HTML generation, add:\n\n- KSHTMLWriter.h\n- KSHTMLWriter.m\n\n### Mac ###\n\nAlternatively, `KSHTMLWriter.xcodeproj` is already set up to build a framework bundle. This includes the `KSWriter` family of classes. Add it to your app's bundle and link against it.\n\nFor WebKit DOM integration, add:\n\n- DOM/*\n\nand link to `WebKit.framework`\n\nPotentially KSHTMLWriter could be built into a framework or static library instead. If you want to do this, feel free to make a fork and add this support; I'll be happy to pull it back into the master.\n\nUsage\n=====\n\n###KSXMLWriter###\n`KSXMLWriter` provides the real meat of the project. Creating elements is very straightforward, and can be thought of as NSXMLParser in reverse. So to write this XML:\n\n    \u003cfoo\u003ebar\u003c/foo\u003e\n\nyou'd do:\n\n    [writer writeElement:@\"foo\" content:^{\n\t\t[writer writeCharacters:@\"bar\"];\n\t}];\n\nSimples! There's easy support for writing element attributes if you need it. Other features:\n\n- Nested elements are pretty printed with correct newlines and indentation\n- Empty elements are automatically written as `\u003cfoo /\u003e`\n- Built-in `-writeComment:` support\n\nIf you need it, there's lower-level API to give precise control over indentation, inline elements, raw text, and element primitives. For more info, read through `KSXMLWriter.h`.\n\n###KSHTMLWriter###\nIf you specifically need to generate (X)HTML, use `KSHTMLWriter`. It adds:\n\n- Many convenience methods for writing common HTML elements and attributes\n- Knowledge of whether an element should be written inline or on its own newline\n- If you enable it, support for HTML 4 and earlier by writing empty elements as `\u003cbr\u003e`\n\n###KSWriter###\n`KSXMLWriter` and `KSHTMLWriter` know how to generate markup, but don't deal with storing that during writing. Instead, we copy a small portion of Java by adopting the concept of a \"writer\".\n\nYou provide the XML writer with a suitable output writer at initialization time. To make life easy for you, NSMutableString is already supported. So to re-use our previous example, you would do:\n\n    NSMutableString *xml = [NSMutableString string];\n    KSXMLWriter *writer = [[KSXMLWriter alloc] initWithOutputWriter:xml];\n    \n    [writer startElement:@\"foo\" attributes:nil];\n    [writer writeCharacters:@\"bar\"];\n    [writer endElement];\n\nThis will neatly append the markup to the mutable string.\n\nYou can easily expand support by adopting `KSWriter` in your own classes. For example, a class that writes directly to disk, rather than an in-memory buffer. `KSXMLWriter` itself already adopts the protocol too, so you could chain multiple writers together if it took your fancy. I'm very interested in adding any new writers people come up with to the project.\n\n###KSStringWriter###\n`KSStringWriter` is a great example of a simple class that implements `KSWriter`. It provides an internal buffer for storing the incoming strings. You can then retrieve the currently written text with a call to `-string`.\n\nThis isn't all that different to writing directly to an `NSMutableString` though, so `KSStringWriter` has a trick up its sleeve. The most expensive aspect of building up a long string is reallocating the underlying buffer to meet demand. `KSStringWriter` lets you work around this by recycling the same writer object. After it's done generating the first string, call `-removeAllCharacters` to reset the written string. It will return to empty, but not free up memory from the old string. The next sequence of writes can be performed quickly into the pre-allocated space, saving time.\n\nIf you do need to reclaim the memory, a call to `-close` will do so.\n\n###XML Entity Escaping###\nAs a bonus, we expose `KSStringXMLEntityEscaping.h/m`. It exposes what `KSXMLWriter` is using internally whenever strings need escaping.\n\nThis is probably an area of the project that needs cleaning up though: better method naming (`ks` as a prefix or similar), documentation, and improved efficiency.\n\n###DOM Integration###\nIn `DOM/KSHTMLWriter+DOM` you'll find code that takes a `DOMElement` (using WebKit.framework, so no iOS support, sorry!) and breaks it up into a series of commands for `KSHTMLWriter`. This is a lot like `-[DOMElement outerHTML]` etc., but more flexible as you can subclass to get hooks into the process if you wish.\n\niOS\n===\niOS support would be nice in the project. There's nothing to stop it that I can see (indeed, it may actually work at the moment for all I know!), but it's not a priority for us right now. If you do want this support, fork, and again I'll be more than happy to pull back into the main project.\n\nCSS\n===\nIt would be nice to apply a similar technique to generating CSS if appropriate. We don't particularly need it at that moment, but there is a placeholder for getting started with in the `CSS` directory.\n\nLicensing\n=========\n\nCopyright © 2010-2013 Karelia Software\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","funding_links":[],"categories":["etc"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarelia%2FKSHTMLWriter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarelia%2FKSHTMLWriter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarelia%2FKSHTMLWriter/lists"}