{"id":13472902,"url":"https://github.com/CDSoft/upp","last_synced_at":"2025-03-26T17:31:27.532Z","repository":{"id":43205916,"uuid":"353804926","full_name":"CDSoft/upp","owner":"CDSoft","description":"UPP is a minimalist and generic text preprocessor using Lua macros.","archived":false,"fork":false,"pushed_at":"2024-10-13T12:50:49.000Z","size":237,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-30T05:26:21.514Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CDSoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-04-01T19:25:17.000Z","updated_at":"2024-10-13T12:50:52.000Z","dependencies_parsed_at":"2024-10-30T03:31:30.164Z","dependency_job_id":null,"html_url":"https://github.com/CDSoft/upp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fupp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fupp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fupp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fupp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CDSoft","download_url":"https://codeload.github.com/CDSoft/upp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245702268,"owners_count":20658577,"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-07-31T16:00:58.899Z","updated_at":"2025-03-26T17:31:27.254Z","avatar_url":"https://github.com/CDSoft.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# Universal PreProcessor\n\n\u003e [!WARNING]\n\u003e This repository is no longer maintained and has been archived.\n\u003e\n\u003e Please consider using [ypp](https://github.com/CDSoft/ypp) instead.\n\n[UPP]: http://cdelord.fr/upp \"Universal PreProcessor\"\n[Panda]: http://cdelord.fr/panda \"Pandoc add-ons (Lua filters for Pandoc)\"\n[Lua]: http://www.lua.org/\n[LuaX]: https://github.com/CDSoft/luax\n[GitHub]: https://github.com/CDSoft/upp\n[cdelord.fr]: http://cdelord.fr\n\nUPP is a minimalist and generic text preprocessor using Lua macros.\n\nIf you need a Pandoc preprocessor, [Panda] may be a better choice.\n\n# Warning: UPP may not be supported in the future\n\nTheir is no plan to support UPP from now on.\nUPP is meant to be replaced by [ypp](http://cdelord.fr/ypp) which combines [UPP] and [Panda] features.\n\n# Open source\n\n[UPP] is an Open source software.\nAnybody can contribute on [GitHub] to:\n\n- suggest or add new features\n- report or fix bugs\n- improve the documentation\n- add some nicer examples\n- find new usages\n- ...\n\n# Installation\n\n## Prerequisites\n\n- [Lua] (version 5.4.4)\n- [LuaX]\n\n## Installation from source\n\n``` sh\n$ git clone https://github.com/CDSoft/luax.git \u0026\u0026 make -C luax install\n$ git clone https://github.com/CDSoft/upp.git\n$ cd upp\n$ make install      # install upp in ~/.local/bin\n```\n\n`make install` installs `upp` in `~/.local/bin`.\nThe `PREFIX` variable can be defined to install `upp` to a different directory\n(e.g. `make install PREFIX=/usr` to install `upp` in `/usr/bin`).\n\n**Note**: `upp` can also be installed with [makex](https://github.com/CDSoft/makex).\n\n## Precompiled binaries\n\nIt is recommended to install upp from the sources.\n\nIn case you need precompiled binaries (`upp` and [Luax](http://cdelord.fr/luax)\ninterpretor included), the latest binaries are available here: [UPP precompiled\nbinaries](http://cdelord.fr/upp/release.html)\n\n## Test\n\n``` sh\n$ make test\n```\n\n# Usage\n\n``` sh\n$ upp [options] files\n```\n\nwhere `files` is the list of files (`-` for `stdin`).\n\noptions:\n\n- `-h`: show help\n- `-l script`: execute a Lua script\n- `-e expression`: execute a Lua expression\n- `-o file`: redirect the output to `file`\n- `-p path`: add a path to `package.path`\n- `-MT name`: add `name` to the target list (see `-MD`)\n- `-MF name`: set the dependency file name\n- `-MD`: generate a dependency file\n\n# Documentation\n\nLua expressions are embedded in the document to process: `$( Lua expression )`\nor `@( Lua expression )`.\n\nLua chunks can also be embedded in the document to add new definitions: `:( Lua\nchunk )` or `@@( Lua chunk )`.\n\nThe `@` notation has been added as it is more Markdown syntax friendly (`$` may\ninterfere with LaTeX equations).\n\nA macro is just a Lua function. Some macros are predefined by `upp`. New macros\ncan be defined by loading Lua scripts (options `-l` and `-e`) or embedded as\nLua chunks.\n\nExpression and chunks can return values. These values are formatted according\nto their types:\n\n- `__tostring` method from a custom metatable: if the value has a `__tostring`\n  metamethod, it is used to format the value\n- arrays (with no `__tostring` metamethod): items are concatenated (with\n  `table.concat`) the separator is the first defined among:\n    - the `sep` field of the table\n    - the global `BLOCK_SEP` variable\n    - `\"\\\\n\"`\n- other types are formatted by the default `tostring` function.\n\n## Example\n\n```\nThe user's home is $(os.getenv \"HOME\").\n```\n\n## Builtin macros\n\n* All Lua and Luax functions and modules are available as `upp` macros\n  (see \u003chttps://www.lua.org/manual/\u003e and \u003chttp://cdelord.fr/luax/#built-in-modules\u003e).\n  E.g.:\n    * `require(module)`: import a Lua script (e.g. to define new macros, variables, ...).\n* `input_files()`: list of the input files given on the command line.\n* `output_file()`: output file given on the command line.\n* `upp(Lua_expression)`: evaluate a Lua expression and outputs its result.\n* `die(msg, errcode)`: print `msg` and exit with the error code `errcode`.\n* `include(filename)`: include a file in the currently preprocessed file.\n* `when(condition)(text)`: process `text` if `condition` is true.\n* `map(f, xs)`: return `{f(x) | x ∈ xs}`.\n* `filter(p, xs)`: return `{x | x ∈ xs ∧ p(x)}`.\n* `range(a, b, [step])`: return `{a, a+step, ..., b}`.\n* `concat(l1, l2, ... ln)`: concatenate the lists `l1`, `l2`, ... `ln` into a new single list.\n* `merge(t1, t2, ... tn)`: merge the fields of the tables `t1`, `t2`, ... `tn` into a new single table.\n* `dirname(path)`: return the directory part of `path`.\n* `basename(path)`: return the filename part of `path`.\n* `join(p1, p2, ... pn)`: build a path (`p1/p2/.../pn`) from the path components `p1`, `p2`, ... `pn`.\n* `sh(cmd)`: run the shell command `cmd` and return its output (`stdout`).\n* `prefix(p)`: build a function that adds the prefix `p` to a string.\n* `suffix(p)`: build a function that adds the suffix `p` to a string.\n* `atexit(f)`: register the function `f`. `f` will be executed before writing the final document.\n* `emit(filename)(content)`: write `content` to a new file named `filename`.\n\n## Example\n\n```\nImport a Lua script: :(require \"module_name\")\nEmbed a Lua script: :( Lua script )\nEvaluate a Lua expression: $( 1 + lua_function(lua_variable) )\nInclude another document: $(include \"other_document_name\")\nConditional text: $(when (lang == \"fr\") [[ Ce texte est écrit en français ! ]])\n```\n\n# Additional packages\n\n`upp` comes with some packages (already included in the binaries, no external\ndependancies are required).\n\n## counter\n\nThe `counter` function generates counters:\n\n* `counter(name, initial_value)`: create a counter named `name` with `initial_value` as the initial value.\n  It returns `initial_value`. The default initial value is `1`.\n* `counter(name)`: incremental the previous value of the counter `name` and returns it.\n\n## req\n\nThe package `req` provides basic requirement management tools.\n\n**Warning**: this package is still experimental and not tested...\n\n# License\n\n    This file is part of UPP.\n\n    UPP is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    UPP is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with UPP.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n    For further information about UPP you can visit\n    http://cdelord.fr/upp\n\n# Feedback\n\nYour feedback and contributions are welcome.\nYou can contact me at [cdelord.fr].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCDSoft%2Fupp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCDSoft%2Fupp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCDSoft%2Fupp/lists"}