Skip to content

Commit

Permalink
Improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ream88
ream88 committed Oct 30, 2023
1 parent 67c0bc6 commit ec32f1f
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 33 deletions.
120 changes: 88 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,42 +10,50 @@ Say something:

```elixir
iex> TwiML.say("Hello") |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Hello</Say>
</Response>)
</Response>\
"""
```

Say 2 things, one after the other:

```elixir
iex> TwiML.say("Hello") |> TwiML.say("world") |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Hello</Say>
<Say>world</Say>
</Response>)
</Response>\
"""
```

Say something in another voice:

```elixir
iex> TwiML.say("Hello", voice: "woman") |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say voice="woman">Hello</Say>
</Response>)
</Response>\
"""
```

Leaving the content empty for a TwiML verb, will create a TwiML element that has
no body:

```elixir
iex> TwiML.hangup() |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Hangup/>
</Response>)
</Response>\
"""
```

You can embed TwiML tags into other tags using the `into_*` function:
Expand All @@ -54,12 +62,14 @@ You can embed TwiML tags into other tags using the `into_*` function:
iex> TwiML.say("Lets say this inside the gather")
...> |> TwiML.into_gather(language: "en-US", input: "speech")
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather language="en-US" input="speech">
<Say>Lets say this inside the gather</Say>
</Gather>
</Response>)
</Response>\
"""
```

If you have multiple TwiML tags you want to embed, that works too:
Expand All @@ -69,13 +79,15 @@ iex> TwiML.say("Hi")
...> |> TwiML.say("We cool?")
...> |> TwiML.into_gather(language: "en-US", input: "speech", hints: "yes, no")
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather language="en-US" input="speech" hints="yes, no">
<Say>Hi</Say>
<Say>We cool?</Say>
</Gather>
</Response>)
</Response>\
"""
```

It is also possible to just include a few of the preceding tags into the body of
Expand All @@ -87,13 +99,15 @@ iex> TwiML.say("Calling Yodel")
...> |> TwiML.number("+1 415-483-0400")
...> |> TwiML.into_dial(1)
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Calling Yodel</Say>
<Dial>
<Number>+1 415-483-0400</Number>
</Dial>
</Response>)
</Response>\
"""
```

The `into_*` functions can take the number of preceding tags, attributes or both
Expand All @@ -106,7 +120,8 @@ iex> TwiML.identity("venkman")
...> |> TwiML.into_client(1, method: "GET")
...> |> TwiML.into_dial(caller: "+1 415-483-0400")
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial caller="+1 415-483-0400">
<Client>
Expand All @@ -116,7 +131,8 @@ iex> TwiML.identity("venkman")
<Identity>stantz</Identity>
</Client>
</Dial>
</Response>)
</Response>\
"""
```

Multiple calls to `into_*` functions allow building complex nested TwiML
Expand All @@ -129,7 +145,8 @@ iex> TwiML.identity("venkman")
...> |> TwiML.into_client(3)
...> |> TwiML.into_dial(1)
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>
<Client>
Expand All @@ -138,56 +155,91 @@ iex> TwiML.identity("venkman")
<Parameter name="last_name" value="Venkman"/>
</Client>
</Dial>
</Response>)
</Response>\
"""
```

Attributes can be provided both as `snake_case` or `camelCase`, but the latter is preferred as the code looks more Elixir-like.

```elixir
iex> TwiML.dial("+1 415-483-0400", recordingStatusCallback: "https://example.org", recording_status_callback_method: "POST")
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial recordingStatusCallback="https://example.org" recordingStatusCallbackMethod="POST">+1 415-483-0400</Dial>
</Response>)
</Response>\
"""
```

Safe binary strings, **IO Data** or **CDATA** are supported as well. Make sure
to only mark actually safe data as safe!

```elixir
iex> TwiML.say({:safe, "<tag>Hello World</tag>"}) |> TwiML.to_xml()
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n <Say><tag>Hello World</tag></Say>\n</Response>"
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say><tag>Hello World</tag></Say>
</Response>\
"""

iex> TwiML.say({:iodata, [104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]}) |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>\n<Response>\n <Say>hello world</Say>\n</Response>)
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>hello world</Say>
</Response>\
"""

iex> TwiML.say({:cdata, "<Hello>\\<World>"}) |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>\n<Response>\n <Say><![CDATA[<Hello>\\<World>]]></Say>\n</Response>)
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say><![CDATA[<Hello>\\<World>]]></Say>
</Response>\
"""
```

This also works with attributes:

```elixir
iex> TwiML.say({:safe, "<tag>Hello World</tag>"}, voice: "Polly.Joanna") |> TwiML.to_xml()
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n <Say voice=\"Polly.Joanna\"><tag>Hello World</tag></Say>\n</Response>"
"""
<?xml version="1.0" encoding="UTF-8\"?>
<Response>
<Say voice="Polly.Joanna"><tag>Hello World</tag></Say>
</Response>\
"""

iex> TwiML.say({:iodata, [104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]}, voice: "Polly.Joanna") |> TwiML.to_xml()
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n <Say voice=\"Polly.Joanna\">hello world</Say>\n</Response>"
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say voice="Polly.Joanna">hello world</Say>
</Response>\
"""

iex> TwiML.say({:cdata, "<Hello>\\<World>"}, voice: "Polly.Joanna") |> TwiML.to_xml()
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n <Say voice=\"Polly.Joanna\"><![CDATA[<Hello>\\<World>]]></Say>\n</Response>"
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say voice="Polly.Joanna"><![CDATA[<Hello>\\<World>]]></Say>
</Response>\
"""
```

Comments can help with debugging (yes, they are somewhat ugly, until `xml_builder` properly supports them):

```elixir
iex> TwiML.comment("Blocked because of insufficient funds") |> TwiML.reject() |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<!-->Blocked because of insufficient funds</!-->
<Reject/>
</Response>)
</Response>\
"""
```

And can also be chained:
Expand All @@ -197,23 +249,27 @@ iex> TwiML.say("Sorry, calls are currently unavailable")
...> |> TwiML.comment("Blocked because of insufficient funds")
...> |> TwiML.reject()
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Sorry, calls are currently unavailable</Say>
<!-->Blocked because of insufficient funds</!-->
<Reject/>
</Response>)
</Response>\
"""
```

Empty attributes are not included in the generated TwiML:

```elixir
iex> TwiML.say("Hello", voice: "", loop: nil)
...> |> TwiML.to_xml()
~s(<?xml version="1.0" encoding="UTF-8"?>
"""
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Hello</Say>
</Response>)
</Response>\
"""
```
<!-- MDOC !-->

Expand Down
6 changes: 5 additions & 1 deletion mix.exs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ defmodule Twiml.MixProject do
deps: deps(),
description: description(),
package: package(),
preferred_cli_env: [
docs: :docs,
"hex.publish": :docs
],

# Docs
name: "TwiML",
Expand All @@ -26,7 +30,7 @@ defmodule Twiml.MixProject do
defp deps do
[
{:xml_builder, "~> 2.2"},
{:ex_doc, "~> 0.24", only: :dev, runtime: false}
{:ex_doc, "~> 0.24", only: :docs}
]
end

Expand Down

0 comments on commit ec32f1f

Please sign in to comment.